diff --git a/README.md b/README.md index 58cfae6a8..bc3cec660 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Many skills in this repo are open source (Apache 2.0). We've also included the d | Skill | Description | |---|---| | [algorithmic-art](./skills/algorithmic-art) | Generative art using p5.js with seeded randomness, flow fields, and particle systems | +| [ascii-mockup](./skills/ascii-mockup) | Mobile-first ASCII art UI wireframes across 5 breakpoints with versioned design tokens, ARIA-compliant color palettes, CDN-served fonts, and zero-hardcode CSS — chains with ux-journey-mapper and frontend-design | | [canvas-design](./skills/canvas-design) | Visual design in PNG/PDF — posters, artwork, and static design pieces | | [frontend-design](./skills/frontend-design) | Production-grade web UIs: pages, components, dashboards, and HTML artifacts | | [slack-gif-creator](./skills/slack-gif-creator) | Animated GIFs optimized for Slack with constraint validation and animation utilities | @@ -127,6 +128,358 @@ The frontmatter requires only two fields: The markdown content below contains the instructions, examples, and guidelines that Claude will follow. For more details, see [How to create custom skills](https://support.claude.com/en/articles/12512198-creating-custom-skills). +--- + +## ASCII Mockup Skill — Demo + +> **Skill invoked:** `ascii-mockup` +> **Project:** Taskflow — a minimal task-management web app +> **Stack:** React / Next.js · Tailwind-compatible tokens · Google Fonts CDN +> **Version:** 1.0.0 · 2026-03-26 + +### ARIA Color Palette + +| Pair | Foreground | Background | Ratio | AA Normal | AA Large | +|---|---|---|---|---|---| +| Body text on surface | `#111827` | `#f9fafb` | **16.0:1** | ✅ | ✅ | +| CTA button label | `#ffffff` | `#2563eb` | **5.9:1** | ✅ | ✅ | +| Ghost button label | `#2563eb` | `#f9fafb` | **4.6:1** | ✅ | ✅ | +| Muted caption on surface | `#6b7280` | `#f9fafb` | **4.6:1** | ✅ | ✅ | +| Status error on surface | `#b91c1c` | `#f9fafb` | **7.1:1** | ✅ | ✅ | + +All pairs meet **WCAG 2.1 AA**. Dark-mode overrides swap surface and text tokens automatically. + +--- + +### tokens.css (excerpt — zero hardcoded values after `:root`) + +```css +@import url('https://fonts.googleapis.com/css2?family=Syne:wght@700;800&family=DM+Sans:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap'); + +:root { + --color-brand-primary: #2563eb; + --color-brand-secondary: #0891b2; + --color-brand-accent: #7c3aed; + + --color-action-primary: var(--color-brand-primary); + --color-action-ghost: transparent; + --color-surface-base: var(--color-neutral-50); + --color-surface-elevated: var(--color-neutral-0); + --color-text-primary: var(--color-neutral-900); + --color-text-muted: var(--color-neutral-500); + --color-border-default: var(--color-neutral-200); + + --font-display: 'Syne', serif; + --font-body: 'DM Sans', sans-serif; + --font-mono: 'JetBrains Mono', monospace; + + --type-scale-base: 1rem; + --type-scale-3xl: 1.875rem; + --space-4: 1rem; + --radius-lg: 0.5rem; + --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1); + --duration-normal: 200ms; + --ease-default: cubic-bezier(0.4, 0, 0.2, 1); +} + +@media (prefers-color-scheme: dark) { + :root { + --color-surface-base: var(--color-neutral-950); + --color-surface-elevated: var(--color-neutral-900); + --color-text-primary: var(--color-neutral-50); + --color-text-muted: var(--color-neutral-400); + --color-border-default: var(--color-neutral-700); + } +} + +@media (prefers-reduced-motion: reduce) { + :root { --duration-normal: 0ms; --duration-fast: 0ms; --duration-slow: 0ms; } +} +``` + +--- + +### ASCII Wireframes — All 5 Breakpoints + +#### `xs` — iPhone 720 · 390px · 48 cols + +``` +╔════════════════════════════════════════════════╗ +║ BREAKPOINT: xs — iPhone 720 · 390px · 48 cols ║ +╚════════════════════════════════════════════════╝ +┌────────────────────────────────────────────────┐ +│ ▓ status bar 9:41 ▲ ●● │ +├────────────────────────────────────────────────┤ +│ ☰ Taskflow 🔔 👤 │ +│ // NAV: sticky · z var(--z-sticky) │ +├────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ Good morning, Alex 👋 │ │ +│ │ You have 4 tasks due today │ │ +│ └──────────────────────────────────────────┘ │ +│ // font: var(--font-display) │ +│ // size: var(--type-scale-3xl) │ +│ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ 🔍 Search tasks… │ │ +│ └──────────────────────────────────────────┘ │ +│ // input: min-height var(--space-12) │ +│ │ +│ ── TODAY ──────────────────────────── 4/7 ── │ +│ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░ │ +│ // progress: var(--color-brand-primary) │ +│ │ +│ ╔══════════════════════════════════════════╗ │ +│ ║ ☐ Write Q2 report [DUE TODAY] ║ │ +│ ║ Project: Marketing · 🔴 High ║ │ +│ ╚══════════════════════════════════════════╝ │ +│ ╔══════════════════════════════════════════╗ │ +│ ║ ☐ Review PR #47 [DUE TODAY] ║ │ +│ ║ Project: Engineering · 🟡 Medium ║ │ +│ ╚══════════════════════════════════════════╝ │ +│ ╔══════════════════════════════════════════╗ │ +│ ║ ☑ Team standup [DONE] ║ │ +│ ║ Project: General · 🟢 Low ║ │ +│ ╚══════════════════════════════════════════╝ │ +│ // card: var(--shadow-md) var(--radius-lg) │ +│ // spacing: var(--space-4) padding │ +│ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ [+ Add New Task] │ │ +│ └──────────────────────────────────────────┘ │ +│ // CTA: var(--color-action-primary) │ +│ // min-height: 44px (touch target WCAG 2.5.5) │ +│ │ +├────────────────────────────────────────────────┤ +│ 🏠 Home 📋 Tasks 📊 Board 👤 Profile │ +│ // bottom nav: env(safe-area-inset-bottom) │ +└────────────────────────────────────────────────┘ +``` + +--- + +#### `sm` — iPad · 768px · 96 cols + +``` +╔════════════════════════════════════════════════════════════════════════════════════════════════╗ +║ BREAKPOINT: sm — iPad · 768px · 96 cols ║ +╚════════════════════════════════════════════════════════════════════════════════════════════════╝ +┌────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Taskflow 🔍 Search tasks… 🔔 Alex ▾ │ +│ // NAV: full horizontal · var(--z-sticky) │ +├──────────────────┬─────────────────────────────────────────────────────────────────────────────┤ +│ SIDEBAR (240px) │ MAIN CONTENT │ +│ ──────────────── │ ───────────────────────────────────────────────────────────────────────── │ +│ 📋 My Tasks │ Good morning, Alex 👋 ▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░ 4 of 7 complete │ +│ 📊 Board │ │ +│ 📁 Projects ▾ │ ┌───────────────────────────────┐ ┌───────────────────────────────────┐ │ +│ · Marketing │ │ ☐ Write Q2 report [DUE TODAY] │ │ ☐ Design system audit [TOMORROW] │ │ +│ · Engineering │ │ Marketing · 🔴 High │ │ Design · 🟡 Medium │ │ +│ · Design │ │ [Edit] [Complete] │ │ [Edit][Complete]│ │ +│ 📅 Calendar │ └───────────────────────────────┘ └───────────────────────────────────┘ │ +│ ──────────────── │ ┌───────────────────────────────┐ ┌───────────────────────────────────┐ │ +│ FILTERS │ │ ☐ Review PR #47 [DUE TODAY] │ │ ☑ Team standup [DONE] │ │ +│ Priority ▾ │ │ Engineering · 🟡 Medium │ │ General · 🟢 Low │ │ +│ Project ▾ │ │ [Edit] [Complete] │ │ [Reopen][View] │ │ +│ Date ▾ │ └───────────────────────────────┘ └───────────────────────────────────┘ │ +│ ──────────────── │ │ +│ [+ New Task] │ [+ Add New Task] │ +└──────────────────┴─────────────────────────────────────────────────────────────────────────────┘ +// SIDEBAR: width 240px · var(--color-surface-elevated) · var(--shadow-md) +// GRID: 2-col cards · gap var(--space-6) +// [+ New Task] sidebar btn: var(--color-action-primary) · width 100% +``` + +--- + +#### `md` — Desktop 1440 · 1440px · 180 cols + +``` +╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗ +║ BREAKPOINT: md — Desktop 1440 · 1440px · 180 cols ║ +╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝ +┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ 🗂 Taskflow 📋 My Tasks 📊 Board 📁 Projects 📅 Calendar 🔍 Search tasks… 🔔 [+ New Task] Alex ▾ │ +├────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────────────────────┤ +│ SIDEBAR │ TASK LIST │ TASK DETAIL PANEL │ +│ ────────── │ ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── │ ───────────────────────── │ +│ 📋 My Tasks │ FILTERS: [All ▾] [Priority ▾] [Project ▾] [Due Date ▾] [Assignee ▾] Sort: Due Date ▲ View: ☰ ⊞ │ Write Q2 report │ +│ 📊 Board │ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── │ │ +│ 📁 Projects ▾ │ ☐ Write Q2 report Marketing 🔴 High Alex Due: Today ▓ 0% [Edit] [Complete] [···] │ 📁 Marketing │ +│ · Marketing │ ☐ Review PR #47 Engineering 🟡 Medium Jordan Due: Today ▓ 0% [Edit] [Complete] [···] │ 🔴 High · Due Today │ +│ · Design │ ☐ Design system audit Design 🟡 Medium Sam Due: Tomorrow ▓ 25% [Edit] [Complete] [···] │ │ +│ · Engineering│ ☐ Update dependencies Engineering 🟢 Low Jordan Due: Fri ▓ 0% [Edit] [Complete] [···] │ Description │ +│ · General │ ☑ Team standup General 🟢 Low Team Completed ✓ [Reopen] [View] │ ┌─────────────────────┐ │ +│ ────────── │ ☐ Client call prep Marketing 🔴 High Alex Due: Fri ▓ 50% [Edit] [Complete] [···] │ │ Draft the Q2 report │ │ +│ PROJECTS │ ☐ Accessibility review Design 🟡 Medium Sam Due: Next Wk ▓ 0% [Edit] [Complete] [···] │ │ for stakeholders··· │ │ +│ ────────── │ │ └─────────────────────┘ │ +│ [+ New Task] │ Showing 7 tasks │ │ +│ │ │ Subtasks (0/3) │ +│ │ │ ☐ Gather metrics │ +│ │ │ ☐ Write exec summary │ +│ │ │ ☐ Peer review │ +│ │ │ [+ Add subtask] │ +└────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────┘ +// 3-PANEL: sidebar 200px · task list flex-1 · detail panel 320px +// ROW hover: var(--color-surface-elevated) · var(--duration-fast) transition +// DETAIL PANEL: var(--shadow-xl) on scroll enter +``` + +--- + +#### `lg` — Desktop 1920 · 1920px · 240 cols + +``` +╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗ +║ BREAKPOINT: lg — Desktop 1920 · 1920px · 240 cols ║ +╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝ +┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ 🗂 Taskflow 📋 Tasks 📊 Board 📁 Projects 📅 Calendar 📈 Analytics 🔍 Search tasks… 🔔 [+ New Task] Alex ▾ ⚙ │ +├──────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────────┤ +│ SIDEBAR 240px│ TASK BOARD — KANBAN │ ANALYTICS PANEL (320px) │ +│ ──────────── │ ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── │ ────────────────────────────────────────────────────────────────── │ +│ 📋 My Tasks │ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ COMPLETION TREND │ +│ 📊 Board │ │ 📥 BACKLOG (12) │ │ 📋 TO DO (5) │ │ 🔄 IN PROGRESS (3) │ │ 👀 REVIEW (2) │ │ ✅ DONE (7) │ │ ┌────────────────────────────────────────────────────────────┐ │ +│ 📁 Projects │ │ ─────────────────── │ │ ─────────────────── │ │ ─────────────────── │ │ ─────────────────── │ │ ─────────────────── │ │ │ 10 │ ▂▄▆█ │ │ +│ Marketing │ │ ╔═══════════════╗ │ │ ╔═══════════════╗ │ │ ╔═══════════════╗ │ │ ╔═══════════════╗ │ │ ╔═══════════════╗ │ │ │ 8 │ ▂▄▆▄▆▄█▄█▆ │ │ +│ Engineering │ │ ║ Update deps ║ │ │ ║ Write Q2 rpt ║ │ │ ║ Design audit ║ │ │ ║ Review PR#47 ║ │ │ ║ Team standup ║ │ │ │ 6 │ ▂▄▆▄▂▄▆▄ │ │ +│ Design │ │ ║ Eng · 🟢 Low ║ │ │ ║ Mkt · 🔴 High ║ │ │ ║ Dsgn ·🟡 Med ║ │ │ ║ Eng ·🟡 Med ║ │ │ ║ Gen · 🟢 Low ║ │ │ │ 4 │ ▂▄▆▄▂▄ │ │ +│ General │ │ ╚═══════════════╝ │ │ ╚═══════════════╝ │ │ ║ ▓▓▓░░░ 25% ║ │ │ ╚═══════════════╝ │ │ ╚═══════════════╝ │ │ │ 2 │ ▂▄▄▄▂ │ │ +│ ────────── │ │ ··· │ │ ··· │ │ ╚═══════════════╝ │ │ ··· │ │ ··· │ │ │ 0 └─────────────────────────────────────────────────────── │ │ +│ 📅 Calendar │ │ │ │ │ │ │ │ │ │ │ │ │ Mon Tue Wed Thu Fri Sat Sun Mon Tue Wed │ │ +│ 📈 Analytics│ │ [+ Add card] │ │ [+ Add card] │ │ [+ Add card] │ │ [+ Add card] │ │ [+ Add card] │ │ └────────────────────────────────────────────────────────────┘ │ +│ ────────── │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │ // chart: inline SVG · colors via currentColor │ +│ [+ New Task]│ │ ────────────────────────────────────────────────────────────────── │ +│ │ │ BY PROJECT TASKS DONE % │ +│ │ │ Marketing ▓▓▓▓▓▓▓▓░░░░ 5 2 40% │ +│ │ │ Engineering ▓▓▓▓▓▓░░░░░░ 4 2 50% │ +│ │ │ Design ▓▓▓▓░░░░░░░░ 3 1 33% │ +│ │ │ General ▓▓▓▓▓▓▓▓▓▓▓▓ 2 2 100% │ +└──────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────┘ +// KANBAN: horizontal scroll on md, native grid on lg · overflow-x auto +// ANALYTICS: sticky right panel, collapsible · var(--shadow-xl) +// CHART: CSS custom-prop colors, no hardcoded fills +``` + +--- + +#### `xl` — UWHD 21:9 · 3440px · 430 cols (center-locked max-width) + +``` +╔════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗ +║ BREAKPOINT: xl — UWHD 21:9 · 3440px · 430 cols [max-width: 1920px centered, gutters fill remainder] ║ +╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝ +░░░░ GUTTER (auto) ░░░░┌──────────────────── max-width: 1920px [identical to lg layout, locked center] ──────────────────────┐░░░░ GUTTER (auto) ░░░░ + │ 🗂 Taskflow [full lg layout reproduced here — sidebar + kanban + analytics] │ + │ // BODY: background var(--color-surface-base) extends edge-to-edge (gutters bleed) │ + │ // CONTENT: max-width 1920px; margin-inline auto │ + │ // GUTTER COLOR: var(--color-surface-base) — no harsh edge │ + │ // FONT: same scale as lg — no increase to avoid readability issues at distance │ + └────────────────────────────────────────────────────────────────────────────────────────────────────────┘ +// UWHD STRATEGY: center-lock with max-width. Never stretch content to full 3440px. +// Gutters intentionally use surface-base to feel like ambient background, not dead space. +// Optional: add a subtle ambient illustration or gradient in the gutter zone. +``` + +--- + +### Component Directory Scaffold (React / Next.js) + +``` +src/ + design-system/ + tokens/ + tokens.json ← source of truth (v1.0.0) + tokens.css ← compiled CSS custom props + Google Fonts @import + tokens.ts ← typed JS: export const color, space, shadow … + components/ + primitives/ + Button/ + Button.tsx ← variant: primary | ghost | danger + Button.module.css ← uses only var(--*) tokens + Input/ + Badge/ + Avatar/ + Icon/ + layout/ + Container/ ← max-width + margin-inline auto + Grid/ ← 12-col responsive + Stack/ ← vertical / horizontal spacing + Divider/ + navigation/ + Navbar/ + Sidebar/ + BottomNav/ ← xs only + Breadcrumb/ + Tabs/ + feedback/ + Toast/ + Alert/ + Modal/ + Skeleton/ + ProgressBar/ + data-display/ + TaskCard/ ← maps to ╔══╗ card in mockup + KanbanColumn/ + StatBar/ + MiniChart/ + forms/ + Form/ + Field/ + Select/ + Checkbox/ + Radio/ + media/ + AspectRatio/ + LazyImage/ + mockups/ + xs/ taskflow-dashboard.txt + sm/ taskflow-dashboard.txt + md/ taskflow-dashboard.txt + lg/ taskflow-dashboard.txt + xl/ taskflow-dashboard.txt + CHANGELOG.md + VERSION +``` + +--- + +### mockups/CHANGELOG.md + +```markdown +## [1.0.0] — 2026-03-26 + +### Added +- Initial 5-breakpoint mockup set: xs, sm, md, lg, xl +- Design token manifest: tokens.json + tokens.css +- ARIA color palette — all pairs meet WCAG 2.1 AA +- Google Fonts CDN: Syne (display) + DM Sans (body) + JetBrains Mono +- Component scaffold for React / Next.js +- Dark mode token overrides +- prefers-reduced-motion support +``` + +### mockups/VERSION + +``` +1.0.0 +``` + +--- + +### Skill Chain — Next Steps + +``` +Step 1 ✅ ascii-mockup → wireframes + tokens (complete) +Step 2 → ux-journey-mapper → overlay task-creation & completion journey on mockup screens +Step 3 → frontend-design → production HTML/CSS/React using tokens.css as the style foundation +``` + +To continue, say: **"Map the task creation journey"** or **"Build the production frontend from these tokens."** + +--- + # Partner Skills Skills are a great way to teach Claude how to get better at using specific pieces of software. As we see awesome example skills from partners, we may highlight some of them here: diff --git a/skills/ascii-mockup/SKILL.md b/skills/ascii-mockup/SKILL.md new file mode 100644 index 000000000..324ecc68b --- /dev/null +++ b/skills/ascii-mockup/SKILL.md @@ -0,0 +1,609 @@ +--- +name: ascii-mockup +description: > + Generate mobile-first ASCII art UI mockups across 5 responsive breakpoints (iPhone 720, iPad, + Desktop 1440, Desktop 1920, UWHD). Maps every UI element to versioned design tokens, produces + ARIA-compliant color palettes, emits CSS custom-property stylesheets with zero hardcoded values, + CDN-references Google Fonts, and chains with the ux-journey-mapper and frontend-design skills to + deliver a full design-to-code workflow. Use when someone asks for wireframes, mockups, ASCII UI, + interface design, design tokens, or responsive layout planning. +license: MIT +--- + +# ASCII Mockup Skill + +Generate comprehensive ASCII art interface mockups that drive a complete, version-controlled +front-end design system. Every run produces: + +1. **ASCII wireframes** at each responsive breakpoint +2. **Design token manifest** (`tokens.json` + `tokens.css`) +3. **Component directory scaffold** matched to the project stack +4. **ARIA-compliant color palette** with contrast scores +5. **Changelog entry** under semantic versioning +6. **Chained skill hooks** to `ux-journey-mapper` and `frontend-design` + +--- + +## Breakpoint Reference + +| ID | Label | Viewport (px) | Char cols | Notes | +|------------|---------------------|-------------------|-----------|--------------------------------| +| `xs` | iPhone 720 portrait | 390 × 844 | 48 | Touch targets ≥ 44px | +| `sm` | iPad tablet | 768 × 1024 | 96 | Two-column grid baseline | +| `md` | Desktop 1440 | 1440 × 900 | 180 | 12-col grid, sidebar + content | +| `lg` | Desktop 1920 | 1920 × 1080 | 240 | Wide content, gutter space | +| `xl` | UWHD (21:9) | 3440 × 1440 | 430 | Ultra-wide, center-locked max | + +Render **all five** unless the user specifies a subset. Always start with `xs` (mobile-first). + +--- + +## ASCII Mockup Format + +Each frame is wrapped in a labeled fence: + +``` +╔══════════════════════════════════════════════════════╗ +║ [BREAKPOINT: xs — iPhone 720 · 390px · 48 cols] ║ +╚══════════════════════════════════════════════════════╝ +┌──────────────────────────────────────────────────────┐ +│ [STATUS BAR] 9:41 ▲ ●●● │ +├──────────────────────────────────────────────────────┤ +│ ☰ Brand Logo 🔔 👤 │ +├──────────────────────────────────────────────────────┤ +│ │ +│ ╔══════════════════════════════════════════════╗ │ +│ ║ HERO SECTION ║ │ +│ ║ ┌────────────────────────────────────────┐ ║ │ +│ ║ │ [HERO IMAGE / VIDEO] │ ║ │ +│ ║ └────────────────────────────────────────┘ ║ │ +│ ║ H1: Page Title Here ║ │ +│ ║ Body copy — short descriptor line ║ │ +│ ║ ┌──────────────┐ ┌──────────────┐ ║ │ +│ ║ │ [CTA btn 1] │ │ [CTA btn 2] │ ║ │ +│ ║ └──────────────┘ └──────────────┘ ║ │ +│ ╚══════════════════════════════════════════════╝ │ +│ │ +└──────────────────────────────────────────────────────┘ +``` + +### ASCII Symbol Conventions + +| Symbol | Meaning | +|-------------------|-------------------------------------| +| `╔╗╚╝║═` | Primary container / card boundary | +| `┌┐└┘│─` | Secondary container / inner panel | +| `[TEXT]` | Interactive element label | +| `〈 〉` | Carousel / slider nav | +| `▓▓▓▓░░░░` | Progress bar (filled / empty) | +| `●●●○○` | Pagination dots / rating | +| `▲▼◀▶` | Sort / chevron direction indicators | +| `☰` | Hamburger menu | +| `🔔 👤 🔍` | Icon placeholders (semantic emoji) | +| `···` | Overflow / truncated content | +| `// ANNOTATION` | Design note inline | + +### Layout Annotations + +After each frame, add an **annotation block**: + +``` +// ANNOTATIONS — xs +// NAV: sticky top, z-index var(--z-nav) +// HERO IMG: aspect-ratio 16/9, object-fit cover, loading="lazy" +// CTA BTN 1: primary action → var(--color-action-primary) +// CTA BTN 2: ghost variant → var(--color-action-ghost) +// SPACING: padding var(--space-4) each side +// FONT: H1 → var(--type-scale-3xl), body → var(--type-scale-base) +``` + +--- + +## Design Token System + +### tokens.json schema + +```json +{ + "meta": { + "name": "", + "version": "1.0.0", + "date": "", + "generator": "ascii-mockup-skill" + }, + "color": { + "brand": { + "primary": { "value": "#", "wcag_on_white": "", "wcag_on_black": "" }, + "secondary": { "value": "#", "wcag_on_white": "", "wcag_on_black": "" }, + "accent": { "value": "#", "wcag_on_white": "", "wcag_on_black": "" } + }, + "semantic": { + "action-primary": { "value": "{color.brand.primary}", "role": "CTA buttons, links" }, + "action-ghost": { "value": "transparent", "role": "Secondary CTA border" }, + "surface-base": { "value": "{color.neutral.50}", "role": "Page background" }, + "surface-elevated": { "value": "{color.neutral.0}", "role": "Cards, modals" }, + "text-primary": { "value": "{color.neutral.900}", "role": "Body & headings" }, + "text-muted": { "value": "{color.neutral.500}", "role": "Captions, metadata" }, + "border-default": { "value": "{color.neutral.200}", "role": "Dividers, card edges" }, + "status-success": { "value": "", "role": "Confirmations" }, + "status-warning": { "value": "", "role": "Alerts" }, + "status-error": { "value": "", "role": "Validation errors" }, + "status-info": { "value": "", "role": "Informational" } + }, + "neutral": { + "0": "#ffffff", "50": "#f9fafb", "100": "#f3f4f6", + "200": "#e5e7eb", "300": "#d1d5db", "400": "#9ca3af", + "500": "#6b7280", "600": "#4b5563", "700": "#374151", + "800": "#1f2937", "900": "#111827", "950": "#030712" + } + }, + "typography": { + "font-family": { + "display": "'', serif", + "body": "'', sans-serif", + "mono": "'', monospace", + "cdn": "https://fonts.googleapis.com/css2?family=&display=swap" + }, + "scale": { + "xs": "0.75rem", "sm": "0.875rem", "base": "1rem", + "lg": "1.125rem", "xl": "1.25rem", "2xl": "1.5rem", + "3xl": "1.875rem", "4xl": "2.25rem", "5xl": "3rem", + "6xl": "3.75rem", "7xl": "4.5rem" + }, + "weight": { "regular": 400, "medium": 500, "semibold": 600, "bold": 700, "extrabold": 800 }, + "leading": { "tight": 1.25, "snug": 1.375, "normal": 1.5, "relaxed": 1.625, "loose": 2 } + }, + "spacing": { + "0": "0", "px": "1px", "0.5": "0.125rem", "1": "0.25rem", + "2": "0.5rem", "3": "0.75rem", "4": "1rem", "5": "1.25rem", + "6": "1.5rem", "8": "2rem", "10": "2.5rem", "12": "3rem", + "16": "4rem", "20": "5rem", "24": "6rem", "32": "8rem" + }, + "radius": { + "none": "0", "sm": "0.25rem", "md": "0.375rem", "lg": "0.5rem", + "xl": "0.75rem", "2xl": "1rem", "3xl": "1.5rem", "full": "9999px" + }, + "shadow": { + "sm": "0 1px 2px 0 rgb(0 0 0 / 0.05)", + "md": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)", + "lg": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)", + "xl": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)", + "2xl": "0 25px 50px -12px rgb(0 0 0 / 0.25)", + "none": "none" + }, + "breakpoint": { + "xs": "390px", "sm": "768px", "md": "1024px", "lg": "1440px", "xl": "1920px", "2xl": "3440px" + }, + "z-index": { + "base": 0, "raised": 10, "dropdown": 100, "sticky": 200, + "overlay": 300, "modal": 400, "toast": 500, "tooltip": 600 + }, + "motion": { + "duration": { "instant": "50ms", "fast": "100ms", "normal": "200ms", "slow": "300ms", "slower": "500ms" }, + "easing": { + "default": "cubic-bezier(0.4, 0, 0.2, 1)", + "in": "cubic-bezier(0.4, 0, 1, 1)", + "out": "cubic-bezier(0, 0, 0.2, 1)", + "spring": "cubic-bezier(0.175, 0.885, 0.32, 1.275)" + } + } +} +``` + +### tokens.css output (always emit this file — zero hardcoded values) + +```css +/* ============================================================================= + DESIGN TOKENS — generated by ascii-mockup-skill v + DO NOT manually edit. Regenerate via: ascii-mockup tokens regenerate + ============================================================================= */ + +/* ── Google Fonts CDN (swap for zero-FOIT) ──────────────────────────────────── */ +@import url('https://fonts.googleapis.com/css2?family=:wght@700;800&family=:wght@400;500;600&family=&display=swap'); + +:root { + /* Color — brand */ + --color-brand-primary: ; + --color-brand-secondary: ; + --color-brand-accent: ; + + /* Color — semantic */ + --color-action-primary: var(--color-brand-primary); + --color-action-ghost: transparent; + --color-surface-base: var(--color-neutral-50); + --color-surface-elevated: var(--color-neutral-0); + --color-text-primary: var(--color-neutral-900); + --color-text-muted: var(--color-neutral-500); + --color-border-default: var(--color-neutral-200); + --color-status-success: ; + --color-status-warning: ; + --color-status-error: ; + --color-status-info: ; + + /* Color — neutral scale */ + --color-neutral-0: #ffffff; + --color-neutral-50: #f9fafb; + --color-neutral-100: #f3f4f6; + --color-neutral-200: #e5e7eb; + --color-neutral-300: #d1d5db; + --color-neutral-400: #9ca3af; + --color-neutral-500: #6b7280; + --color-neutral-600: #4b5563; + --color-neutral-700: #374151; + --color-neutral-800: #1f2937; + --color-neutral-900: #111827; + --color-neutral-950: #030712; + + /* Typography */ + --font-display: , serif; + --font-body: , sans-serif; + --font-mono: , monospace; + + --type-scale-xs: 0.75rem; + --type-scale-sm: 0.875rem; + --type-scale-base: 1rem; + --type-scale-lg: 1.125rem; + --type-scale-xl: 1.25rem; + --type-scale-2xl: 1.5rem; + --type-scale-3xl: 1.875rem; + --type-scale-4xl: 2.25rem; + --type-scale-5xl: 3rem; + --type-scale-6xl: 3.75rem; + --type-scale-7xl: 4.5rem; + + --font-weight-regular: 400; + --font-weight-medium: 500; + --font-weight-semibold: 600; + --font-weight-bold: 700; + --font-weight-extrabold: 800; + + --leading-tight: 1.25; + --leading-snug: 1.375; + --leading-normal: 1.5; + --leading-relaxed: 1.625; + --leading-loose: 2; + + /* Spacing */ + --space-0: 0; + --space-px: 1px; + --space-0\5: 0.125rem; + --space-1: 0.25rem; + --space-2: 0.5rem; + --space-3: 0.75rem; + --space-4: 1rem; + --space-5: 1.25rem; + --space-6: 1.5rem; + --space-8: 2rem; + --space-10: 2.5rem; + --space-12: 3rem; + --space-16: 4rem; + --space-20: 5rem; + --space-24: 6rem; + --space-32: 8rem; + + /* Border radius */ + --radius-none: 0; + --radius-sm: 0.25rem; + --radius-md: 0.375rem; + --radius-lg: 0.5rem; + --radius-xl: 0.75rem; + --radius-2xl: 1rem; + --radius-3xl: 1.5rem; + --radius-full: 9999px; + + /* Shadow */ + --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05); + --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1); + --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1); + --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1); + --shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25); + --shadow-none: none; + + /* Z-index */ + --z-base: 0; + --z-raised: 10; + --z-dropdown: 100; + --z-sticky: 200; + --z-overlay: 300; + --z-modal: 400; + --z-toast: 500; + --z-tooltip: 600; + + /* Motion */ + --duration-instant: 50ms; + --duration-fast: 100ms; + --duration-normal: 200ms; + --duration-slow: 300ms; + --duration-slower: 500ms; + + --ease-default: cubic-bezier(0.4, 0, 0.2, 1); + --ease-in: cubic-bezier(0.4, 0, 1, 1); + --ease-out: cubic-bezier(0, 0, 0.2, 1); + --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275); +} + +/* Dark mode token overrides */ +@media (prefers-color-scheme: dark) { + :root { + --color-surface-base: var(--color-neutral-950); + --color-surface-elevated: var(--color-neutral-900); + --color-text-primary: var(--color-neutral-50); + --color-text-muted: var(--color-neutral-400); + --color-border-default: var(--color-neutral-700); + } +} + +/* Reduced motion */ +@media (prefers-reduced-motion: reduce) { + :root { + --duration-instant: 0ms; + --duration-fast: 0ms; + --duration-normal: 0ms; + --duration-slow: 0ms; + --duration-slower: 0ms; + } +} +``` + +--- + +## ARIA Color Compliance + +For every color pair used in the design, compute and report: + +| Pair | Foreground | Background | Ratio | AA Normal | AA Large | AAA Normal | AAA Large | +|---------------------------|-------------|-------------|--------|-----------|----------|------------|-----------| +| Body text on surface | # | # | N.N:1 | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ | +| CTA button label | # | # | N.N:1 | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ | +| Muted text on surface | # | # | N.N:1 | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ | +| Status error on surface | # | # | N.N:1 | ✅/❌ | ✅/❌ | ✅/❌ | ✅/❌ | + +**Minimum requirements:** AA Normal (4.5:1) for all body text; AA Large (3:1) for headings and UI +components ≥ 18pt or 14pt bold. Flag anything below AA. Suggest accessible alternatives. + +**WCAG 2.1 Relative Luminance formula:** +``` +L = 0.2126 × R_lin + 0.7152 × G_lin + 0.0722 × B_lin + where X_lin = (X/255)^2.2 (simplified sRGB linearisation) +Contrast ratio = (L_lighter + 0.05) / (L_darker + 0.05) +``` + +--- + +## Component Directory Scaffold + +After generating mockups, propose a directory structure tuned to the detected (or specified) stack. +Default to framework-agnostic Web Components if no stack is given. + +### React / Next.js +``` +src/ + design-system/ + tokens/ + tokens.json ← source of truth + tokens.css ← compiled CSS custom props + tokens.ts ← typed JS exports (const colors = {...}) + components/ + primitives/ ← Button, Input, Badge, Avatar, Icon + layout/ ← Container, Grid, Stack, Divider + navigation/ ← Navbar, Sidebar, Breadcrumb, Tabs + feedback/ ← Toast, Alert, Modal, Skeleton + data-display/ ← Card, Table, List, Stat + forms/ ← Form, Field, Select, Checkbox, Radio + media/ ← Image, Video, AspectRatio + mockups/ + xs/ ← ASCII frames per breakpoint + sm/ + md/ + lg/ + xl/ + CHANGELOG.md ← semantic version history of mockups + VERSION ← current version string +``` + +### Vue / Nuxt +``` +src/ + design-system/ + tokens/ ... ← same as above + components/ + base/ ← BaseButton, BaseInput … + layout/ + navigation/ + feedback/ + display/ + forms/ + mockups/ ... +``` + +### HTML / Vanilla / Web Components +``` +design-system/ + tokens/ + components/ + buttons/ + cards/ + navigation/ + forms/ + layout/ + mockups/ +``` + +--- + +## Versioning Protocol + +Every time mockups are regenerated or tokens are changed: + +1. Bump `VERSION` using SemVer: + - **Patch** (x.x.N): annotation-only text changes + - **Minor** (x.N.0): layout changes within existing components + - **Major** (N.0.0): breakpoint additions, token schema changes, new sections +2. Append to `mockups/CHANGELOG.md`: + +```markdown +## [1.2.0] — 2026-03-26 + +### Changed +- Hero section: added secondary CTA button across all breakpoints +- Token: `--color-brand-primary` updated from #2563eb → #1d4ed8 + +### Added +- `xl` (UWHD) breakpoint frame + +### Fixed +- xs nav: hamburger touch target increased to 44px minimum +``` + +3. Include `` as the first comment in every emitted HTML file. + +--- + +## User-Agent Responsive Behavior + +When generating HTML output (or CSS media queries), account for user-agent capabilities: + +```css +/* Touch device — enlarge tap targets */ +@media (pointer: coarse) { + --min-tap-target: 44px; +} + +/* Fine pointer (desktop mouse) */ +@media (pointer: fine) { + --min-tap-target: 24px; +} + +/* High-DPI screens */ +@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) { + /* Serve @2x assets via srcset; no hardcoded background-image URLs */ +} + +/* Print */ +@media print { + --color-surface-base: #ffffff; + --color-text-primary: #000000; + --shadow-md: none; +} +``` + +Explicitly call out UA-specific behaviors in annotations (e.g., iOS safe-area insets +`env(safe-area-inset-*)`, Android chrome notch handling). + +--- + +## Performance Checklist + +Embed this block in every HTML artifact generated: + +```html + + + + + + + + + + + + + + + + + +``` + +--- + +## Skill Chain Workflow + +This skill integrates with: + +### → ux-journey-mapper +After generating mockups, invoke the `ux-journey-mapper` skill to: +- Map each mockup screen to a journey stage (awareness → onboarding → retention) +- Tag touchpoints with the ASCII component references +- Export `.journey.md` + Mermaid swimlane auto-annotated with mockup version + +### → frontend-design +After token and mockup approval, invoke `frontend-design` to: +- Receive `tokens.json` as the aesthetic foundation +- Build production HTML/CSS/JS using `tokens.css` custom properties +- Apply all ARIA color pairs from the compliance table +- Wire all breakpoints using the verified CSS variables + +### → theme-factory +Optionally hand off `tokens.json` to `theme-factory` to apply the palette across slides or docs. + +### Invocation hint +``` +Step 1: ascii-mockup → wireframes + tokens +Step 2: ux-journey-mapper → journey map overlaid on mockup screens +Step 3: frontend-design → production code using the token stylesheet +``` + +--- + +## Workflow — Step by Step + +When this skill is invoked: + +1. **Gather context** — ask for (or infer from conversation): + - Project name and purpose + - Target audience / primary personas + - Preferred stack (React, Vue, HTML, etc.) + - Brand seed colors (or generate a compliant palette) + - Font preferences (or recommend from Google Fonts) + - Which screens / flows to wireframe + +2. **Author ARIA palette** — pick 3–5 brand colors, compute all contrast ratios, + flag failures, suggest alternatives until all pairs are AA compliant. + +3. **Emit `tokens.json`** — fill every token category with the chosen palette, + typography, spacing, motion values. + +4. **Emit `tokens.css`** — compiled from `tokens.json`, Google Fonts `@import` at top. + +5. **Generate ASCII mockups** — render all 5 breakpoints, mobile-first (xs first). + Annotate every element with its token reference. + +6. **Propose component directory** — list each ASCII element as a named component + with its directory path and reuse scope. + +7. **Write CHANGELOG entry** — bump version, record what changed. + +8. **Offer skill-chain** — ask user if they want to continue with + `ux-journey-mapper` → `frontend-design`. + +--- + +## Quality Gates + +Before finalizing output, verify: + +- [ ] All 5 breakpoints rendered (xs → xl) +- [ ] Every color pair in the palette has a computed contrast ratio +- [ ] No hardcoded hex/px/rem values in `tokens.css` (only `var(--*)` references after `:root`) +- [ ] Google Fonts `@import` present with `display=swap` +- [ ] Each ASCII element annotated with its token name +- [ ] `CHANGELOG.md` entry written +- [ ] `VERSION` file contains current SemVer string +- [ ] Component directory scaffold provided +- [ ] Performance checklist block included in any HTML output +- [ ] `prefers-color-scheme: dark` override block in `tokens.css` +- [ ] `prefers-reduced-motion` block in `tokens.css` + +--- + +## Design Feedback Protocol + +If the user's request has gaps or anti-patterns, provide brief feedback: + +- **Inaccessible colors**: "Your requested `#ff0` on `#fff` is 1.07:1 — fails all WCAG levels. Suggest `#7a7a00` (8.5:1 on white) for body, `#ffdd00` on `#1a1a00` for display use." +- **Missing mobile consideration**: "No xs breakpoint specified — adding mobile-first as it covers 60%+ of web traffic." +- **Hardcoded fonts**: "Avoid embedding fonts as local files — Google Fonts CDN reduces load time and benefits from shared browser caching." +- **Touch target too small**: "Buttons at 32px fail WCAG 2.5.5 (Target Size) on touch devices — minimum 44×44px recommended." +- **Single breakpoint request**: "Designing only for desktop leaves ~50% of users underserved — generating all 5 breakpoints for a complete responsive system."