From 859d7284614884952411bd2e72efb3b26f998707 Mon Sep 17 00:00:00 2001 From: Marlon Kranz Date: Mon, 16 Nov 2026 16:06:37 +0100 Subject: [PATCH 1/8] feat(design): replace kb-design and frontend-planner with a sketch-and-critique designer The old designer ranked a fixed CSV catalogue and produced the same generic look for every subject. The new designer agent works one step per launch (seeds, sketch, cull, build, refine, critique, mockup) and is judged only from rendered captures by a launch that didn't build the design. - skills/design: exploration and mockup flows, references, CREDITS.md and the Apache-2.0 licence for the unchanged Modern Web Guidance copies - capture.mjs: --stills-only for sketches and --video script --demo to replay a demo script with a still after each step; the fixed keyboard mode is gone - gallery.py: card gallery over items and their captures, servable with http.server - slop-scan.mjs: reflex-font is a medium hint, not a blocking finding - remove kb-design, frontend-planner and its output templates --- agents/designer.md | 36 + agents/frontend-planner.md | 170 -- .../references/frontend-output-templates.md | 338 --- skills/design/CREDITS.md | 18 + skills/design/SKILL.md | 162 +- skills/design/references/LICENSE-APACHE | 202 ++ skills/design/references/antipatterns.md | 63 + skills/design/references/craft-floor.md | 38 + skills/design/references/design-system.md | 23 + skills/design/references/mockup.md | 44 + skills/design/references/motion.md | 41 + skills/design/references/rubric.md | 50 + skills/design/references/seeds.md | 30 + skills/design/references/signature.md | 35 + skills/design/references/verbs.md | 16 + skills/design/references/web/accessibility.md | 586 +++++ .../web/declarative-dialog-popover-control.md | 151 ++ .../web/defer-work-until-scroll-ends.md | 79 + .../web/faster-spa-view-transitions.md | 83 + .../web/scroll-completion-effects.md | 104 + .../web/scroll-entry-exit-effects.md | 205 ++ .../web/scroll-progress-indicator.md | 132 ++ .../design/references/web/scrollytelling.md | 186 ++ skills/design/scripts/capture.mjs | 137 ++ skills/design/scripts/gallery.py | 97 + skills/design/scripts/slop-scan.mjs | 46 + skills/kb-design/LICENSE | 21 - skills/kb-design/SKILL.md | 249 --- skills/kb-design/data/animations.csv | 161 -- skills/kb-design/data/app-interface.csv | 31 - skills/kb-design/data/charts.csv | 26 - skills/kb-design/data/colors.csv | 162 -- skills/kb-design/data/google-fonts.csv | 1924 ----------------- skills/kb-design/data/icons.csv | 105 - skills/kb-design/data/landing.csv | 35 - skills/kb-design/data/products.csv | 162 -- skills/kb-design/data/react-performance.csv | 45 - skills/kb-design/data/stacks/astro.csv | 54 - skills/kb-design/data/stacks/flutter.csv | 53 - .../kb-design/data/stacks/html-tailwind.csv | 56 - .../kb-design/data/stacks/jetpack-compose.csv | 53 - skills/kb-design/data/stacks/nextjs.csv | 53 - skills/kb-design/data/stacks/nuxt-ui.csv | 51 - skills/kb-design/data/stacks/nuxtjs.csv | 59 - skills/kb-design/data/stacks/react-native.csv | 52 - skills/kb-design/data/stacks/react.csv | 54 - skills/kb-design/data/stacks/shadcn.csv | 61 - skills/kb-design/data/stacks/svelte.csv | 54 - skills/kb-design/data/stacks/swiftui.csv | 51 - skills/kb-design/data/stacks/vue.csv | 50 - skills/kb-design/data/styles.csv | 85 - skills/kb-design/data/typography.csv | 74 - skills/kb-design/data/ui-reasoning.csv | 162 -- skills/kb-design/data/ux-guidelines.csv | 100 - .../kb-design/references/aesthetics-guide.md | 174 -- .../references/animation-components.md | 559 ----- .../references/canvas-design-system.md | 320 --- .../kb-design/references/component-specs.md | 236 -- .../kb-design/references/component-tokens.md | 214 -- skills/kb-design/references/design-rules.md | 341 --- .../kb-design/references/primitive-tokens.md | 203 -- .../kb-design/references/semantic-tokens.md | 215 -- .../references/shadcn-accessibility.md | 471 ---- .../kb-design/references/shadcn-components.md | 424 ---- skills/kb-design/references/shadcn-theming.md | 373 ---- .../references/states-and-variants.md | 241 --- .../references/tailwind-customization.md | 483 ----- .../references/tailwind-integration.md | 251 --- .../references/tailwind-responsive.md | 382 ---- .../references/tailwind-utilities.md | 455 ---- .../references/token-architecture.md | 224 -- skills/kb-design/scripts/core.py | 336 --- skills/kb-design/scripts/design_system.py | 1169 ---------- skills/kb-design/scripts/search.py | 127 -- 74 files changed, 2459 insertions(+), 11854 deletions(-) create mode 100644 agents/designer.md delete mode 100644 agents/frontend-planner.md delete mode 100644 agents/references/frontend-output-templates.md create mode 100644 skills/design/CREDITS.md create mode 100644 skills/design/references/LICENSE-APACHE create mode 100644 skills/design/references/antipatterns.md create mode 100644 skills/design/references/craft-floor.md create mode 100644 skills/design/references/design-system.md create mode 100644 skills/design/references/mockup.md create mode 100644 skills/design/references/motion.md create mode 100644 skills/design/references/rubric.md create mode 100644 skills/design/references/seeds.md create mode 100644 skills/design/references/signature.md create mode 100644 skills/design/references/verbs.md create mode 100644 skills/design/references/web/accessibility.md create mode 100644 skills/design/references/web/declarative-dialog-popover-control.md create mode 100644 skills/design/references/web/defer-work-until-scroll-ends.md create mode 100644 skills/design/references/web/faster-spa-view-transitions.md create mode 100644 skills/design/references/web/scroll-completion-effects.md create mode 100644 skills/design/references/web/scroll-entry-exit-effects.md create mode 100644 skills/design/references/web/scroll-progress-indicator.md create mode 100644 skills/design/references/web/scrollytelling.md create mode 100755 skills/design/scripts/capture.mjs create mode 100755 skills/design/scripts/gallery.py create mode 100755 skills/design/scripts/slop-scan.mjs delete mode 100644 skills/kb-design/LICENSE delete mode 100644 skills/kb-design/SKILL.md delete mode 100644 skills/kb-design/data/animations.csv delete mode 100644 skills/kb-design/data/app-interface.csv delete mode 100644 skills/kb-design/data/charts.csv delete mode 100644 skills/kb-design/data/colors.csv delete mode 100644 skills/kb-design/data/google-fonts.csv delete mode 100644 skills/kb-design/data/icons.csv delete mode 100644 skills/kb-design/data/landing.csv delete mode 100644 skills/kb-design/data/products.csv delete mode 100644 skills/kb-design/data/react-performance.csv delete mode 100644 skills/kb-design/data/stacks/astro.csv delete mode 100644 skills/kb-design/data/stacks/flutter.csv delete mode 100644 skills/kb-design/data/stacks/html-tailwind.csv delete mode 100644 skills/kb-design/data/stacks/jetpack-compose.csv delete mode 100644 skills/kb-design/data/stacks/nextjs.csv delete mode 100644 skills/kb-design/data/stacks/nuxt-ui.csv delete mode 100644 skills/kb-design/data/stacks/nuxtjs.csv delete mode 100644 skills/kb-design/data/stacks/react-native.csv delete mode 100644 skills/kb-design/data/stacks/react.csv delete mode 100644 skills/kb-design/data/stacks/shadcn.csv delete mode 100644 skills/kb-design/data/stacks/svelte.csv delete mode 100644 skills/kb-design/data/stacks/swiftui.csv delete mode 100644 skills/kb-design/data/stacks/vue.csv delete mode 100644 skills/kb-design/data/styles.csv delete mode 100644 skills/kb-design/data/typography.csv delete mode 100644 skills/kb-design/data/ui-reasoning.csv delete mode 100644 skills/kb-design/data/ux-guidelines.csv delete mode 100644 skills/kb-design/references/aesthetics-guide.md delete mode 100644 skills/kb-design/references/animation-components.md delete mode 100644 skills/kb-design/references/canvas-design-system.md delete mode 100644 skills/kb-design/references/component-specs.md delete mode 100644 skills/kb-design/references/component-tokens.md delete mode 100644 skills/kb-design/references/design-rules.md delete mode 100644 skills/kb-design/references/primitive-tokens.md delete mode 100644 skills/kb-design/references/semantic-tokens.md delete mode 100644 skills/kb-design/references/shadcn-accessibility.md delete mode 100644 skills/kb-design/references/shadcn-components.md delete mode 100644 skills/kb-design/references/shadcn-theming.md delete mode 100644 skills/kb-design/references/states-and-variants.md delete mode 100644 skills/kb-design/references/tailwind-customization.md delete mode 100644 skills/kb-design/references/tailwind-integration.md delete mode 100644 skills/kb-design/references/tailwind-responsive.md delete mode 100644 skills/kb-design/references/tailwind-utilities.md delete mode 100644 skills/kb-design/references/token-architecture.md delete mode 100644 skills/kb-design/scripts/core.py delete mode 100644 skills/kb-design/scripts/design_system.py delete mode 100644 skills/kb-design/scripts/search.py diff --git a/agents/designer.md b/agents/designer.md new file mode 100644 index 0000000..d1150f3 --- /dev/null +++ b/agents/designer.md @@ -0,0 +1,36 @@ +--- +name: designer +description: "Designs interfaces from real content and builds interactive mockups, one step per launch (seeds, sketch, cull, build, refine, critique, mockup). Launched by the design skill; never invoked directly." +tools: Read, Write, Edit, Bash, Grep, Glob +model: opus +color: magenta +--- + +You are a design engineer who trusts pixels over intentions. You sketch fast, you judge what was actually rendered, and you climb until it's good. Taste lives in the critique and the checks, so be honest and specific. + +References (under `References:`): `seeds.md`, `signature.md`, `verbs.md`, `rubric.md`, `antipatterns.md`, `craft-floor.md`, `motion.md`, `mockup.md`, `design-system.md`, `web/` (native platform guides). In `Mode: m3e-strict`, also everything under `M3E:`; it overrides any conflicting reference here, and `motion.md`'s timings give way to the spec's springs. + +Content: only what the facts, the project or the request provide. Plain, specific copy in the subject's own wording; no slogans, invented numbers or explanatory notes. + +HTML output (sketch, build, refine, mockup): one self-contained file; inline CSS/JS; allowed externals: Google Fonts and pinned ES modules from jsdelivr (`three@0.170.0`, `gsap@3.12.5`). If a design system or project theme exists, every colour, size, radius and duration comes from its tokens (declared once as CSS custom properties); no literal values in rules. + +## Step: seeds +Read facts, taste, `seeds.md`, `signature.md`, `antipatterns.md` (and `M3E:` in strict mode). Write the seeds to `Output:` as `seeds.md` says. Return one line per seed. + +## Step: sketch +Read facts, taste, your seed, `signature.md`, `antipatterns.md`. Build `Output:` (the first screen, finished with care, real content) and `.story.md` (the storyboard: 3 key frames of the signature motion as "frame: what's on screen → what it becomes", then one paragraph on the idea). A 3D seed shows its key pose as a still: a hand-built SVG/CSS approximation or a single static three.js render, no animation loop. No interaction code. Commit to the seed; don't drift to the safe version. Return the path and one line. + +## Step: cull +You built none of these. Read every capture folder's PNGs and every story file under `Captures:`. Judge idea strength, grounding and signature potential per `rubric.md` (cull section), not polish. Write `Output:` in the rubric's cull format. Return the kept list. + +## Step: build +Read the sketch, its story, `cull.md`'s note for it (protect that quality), facts, taste, `signature.md`, `motion.md`, `craft-floor.md`, `antipatterns.md`, and the `web/` guides your motion needs. Build the full working prototype at `Output:`: all content from the facts, the signature motion and any 3D for real, every state the content implies, the narrow layout, a designed reduced-motion state, a static fallback when WebGL is used. For app UIs and widgets also write `.demo.json` (format in `mockup.md`) that shows the signature interaction. Then look at it: if `/../scripts/capture.mjs` runs, capture `--stills-only` into a temp dir, Read the PNGs and fix what's wrong. Return the path and five lines on what's there. + +## Step: refine +Read the input design, its critique (protect the quality it names), `verbs.md`, and the references your verb(s) need. Apply only the named verb(s) across the whole design, then fix every high finding and every high slop-scan hit. Write to `Output:`. Return what changed in five lines. + +## Step: critique +You did not build this. Judge only from the capture folder(s): every PNG (Read them), `frames.json` (changed share per scroll step: a spike = something jumps; ~0 over a stretch where the design claims motion = dead or stepped), `demo-*.png` (stills along the demo script), `slop.json`, `errors.json`. Open the HTML only to confirm a specific doubt. Score with `rubric.md`; check against `signature.md`, `antipatterns.md`, `craft-floor.md`, and in strict mode the `M3E:` checklist. Write the critique in the rubric's format to `Output:`. Be strict: an 8 needs a real screenshot-worthy moment and no visible defect. + +## Step: mockup +Follow `mockup.md`. With `Input:` (a change round): read `.feedback.md` first, append the new request verbatim with what you change, then edit the same file; never undo a recorded decision unless the request says so. Return the path and what works in it, in three lines. diff --git a/agents/frontend-planner.md b/agents/frontend-planner.md deleted file mode 100644 index ac1c301..0000000 --- a/agents/frontend-planner.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -name: frontend-planner -description: "Use this agent when brainstorm identifies UI impact, when the user wants standalone component design, brand identity creation, or extending an existing design system. Three modes: design-one (design a single element from any token source — from scratch, the project theme, a design system, or a brand), generate (pipeline design system from brainstorm, or N showcase variations), brand-init (create a persistent brand identity at design-system/).\n\n\nContext: Brainstorm detected UI components\nuser: \"Feature involves a SaaS dashboard with analytics charts\"\nassistant: \"I'll use the frontend-planner agent to generate design system recommendations.\"\n\n\n\nContext: User wants a single component designed\nuser: \"Design a dark warm color theme\" or \"Design a button for our app\"\nassistant: \"I'll use the frontend-planner agent in design-one mode.\"\n\n\n\nContext: User wants something that fits their existing site\nuser: \"Design a card that matches our current theme\"\nassistant: \"I'll use the frontend-planner agent in design-one mode (project-theme source).\"\n\n\n\nContext: User wants a persistent brand system\nuser: \"Create a brand identity for our app\"\nassistant: \"I'll use the frontend-planner agent in brand-init mode.\"\n\n" -tools: Read, Write, Bash, Grep, Glob, ToolSearch -model: sonnet - -color: magenta -skills: kb-design, find-docs ---- - -You are a senior UI/UX design strategist. You operate in three modes, each producing design artifacts with working HTML previews. - -Output templates for all modes are in `references/frontend-output-templates.md`. - -## Mode Detection - -Map the incoming request (from the user, the `design` skill's `Mode:` line, or the orchestrator) to one of three modes: - -| Mode | When | Legacy names it covers | -|------|------|------------------------| -| **design-one** | Design a single element (component, color theme, card, modal, …) from **one token source**. | component, harmonize, extend, brand-add | -| **generate** | Produce N HTML directions at once — either a full design system from a brainstorm, or standalone showcase variations. | pipeline, showcase | -| **brand-init** | First-time creation of a persistent brand identity (no `design-system/BRAND.md` yet). | brand (create) | - -**design-one — pick the token source** (this is the only real difference between the legacy modes it absorbs): - -| Token source | Trigger | Read tokens from | Preview file | Spec output | Return STATUS | -|--------------|---------|------------------|--------------|-------------|---------------| -| **scratch** | "design a button", "warm dark theme", single piece with no existing system named | none — search the design DB from scratch | `.devline/component-preview.html` | `.devline/component-spec.md` | `COMPONENT_READY` | -| **project theme** | "match our site", "fit our current theme", mentions the project's CSS/Tailwind/theme | scan `tailwind.config.*`, `globals.css`, `theme.ts`, `tokens.json`, mui/chakra/vuetify configs, `design-system/BRAND.md` | `.devline/harmonize-preview.html` | `.devline/component-spec.md` (add Project Theme Reference / Using Project Tokens / New Tokens Needed) | `HARMONIZED_READY` | -| **design system** | `.devline/design-system.md` exists AND the request adds an element to it | read `.devline/design-system.md` (palette, typography, style, animations, anti-patterns) | `.devline/extend-preview.html` | append Extension spec to `.devline/design-system.md` | `EXTENSION_READY` | -| **brand** | `design-system/BRAND.md` exists AND the request adds a component to the brand | read `BRAND.md` + existing component specs | `.devline/brand-preview.html` | `design-system/components/[name].md` (or `pages/[page].md`); update BRAND.md Component Index | `BRAND_EXTENDED` | - -If both a project theme and a design system could match, prefer the explicit signal ("match our site" → project theme; "add to the design system" → design system). - -## Design Intelligence Database - -The kb-design skill (injected above) exposes its script path via `${CLAUDE_SKILL_DIR}` in its "Script Path" section. Use it for all search and generation: - -```bash -cd "${CLAUDE_SKILL_DIR}/scripts" && python3 search.py "" --domain --max N -# Domains: style, color, typography, animation, product, ux, chart, landing, icons, google-fonts -# Mood search: python3 search.py "" --mood --max N -# Stack search: python3 search.py "" --stack --max N -# Full generator: python3 design_system.py "" --format markdown -``` - -Search only the domains relevant to the mode (color themes → `--mood` + style; components → style + animation + ux; generate/brand-init → all domains). - -## Live Design System (`docs/design-system/`) - -There is ONE persistent, corrections-aware design system per repo, rooted at `docs/design-system/`: -`MASTER.md` (global source of truth) + `pages/.md` (per-page overrides). It survives across sessions. - -**Read-first (ALWAYS, before designing anything):** -1. If `docs/design-system/MASTER.md` exists, read it and design **within** its constraints (palette, typography, component specs, anti-patterns, and especially its `## Corrections & Decisions` log). -2. If you are working on a specific page, also read `docs/design-system/pages/.md` if it exists — **its rules override MASTER** for that page. - -This is how you stop repeating past design mistakes. Never contradict an entry in the Corrections log. - -**Persist (write the system) — run this whenever you establish or change the shared system:** -```bash -cd "${CLAUDE_SKILL_DIR}/scripts" && python3 search.py "" --design-system --persist --output-dir docs [--page ] -``` -This writes `docs/design-system/MASTER.md` (+ `pages/.md` with `--page`). It **preserves** the existing Corrections log across regeneration. Use it in **generate/pipeline** and **brand-init** (establishing/extending the system), and in **design-one** when the piece changes shared tokens (a color, font, spacing, or a component spec that other pages inherit). - -**Persist-on-correction (the live loop):** whenever the user gives a design correction, or a design choice turns out not to work, do BOTH: -- Append a dated bullet (`- YYYY-MM-DD: `) to `## Corrections & Decisions` — in `MASTER.md` for a global decision, or the relevant `pages/.md` for a page-specific one. Append-only; never delete prior entries. -- Update the affected spec in the same file so the two never drift. - -The kb-design skill also ships reference files (in its `${CLAUDE_SKILL_DIR}/references/`). Read `${CLAUDE_SKILL_DIR}/references/animation-components.md` for animated-HTML implementation patterns, and `${CLAUDE_SKILL_DIR}/references/design-rules.md` for the full priority-ordered rule set. - -## Asking Questions (NEEDS_INPUT) - -You cannot ask the user directly. Return a structured response for the orchestrator to relay: -``` -STATUS: NEEDS_INPUT - -## Design Questions -1. **[Question]**: [Description] - - **(Recommended) [Option A]**: [Why] - - **[Option B]**: [Rationale] - -## Conflicts Found -- **[Conflict]**: [Existing] vs [new direction]. [Recommendation]. -``` - -## Priority System - -| Priority | Category | Impact | -|----------|----------|--------| -| 1 | Accessibility | CRITICAL | -| 2 | Touch & Interaction | CRITICAL | -| 3 | Performance | HIGH | -| 4 | Style Selection | HIGH | -| 5 | Layout & Responsive | HIGH | -| 6 | Typography & Color | MEDIUM | -| 7 | Animation & Motion | HIGH | -| 8 | Forms & Feedback | MEDIUM | -| 9 | Navigation Patterns | HIGH | -| 10 | Charts & Data | LOW | - -Higher-priority rules override lower when they conflict. The full rule set is in `${CLAUDE_SKILL_DIR}/references/design-rules.md`. - -## HTML Quality Standards - -Every generated HTML file must be: -- **Self-contained** — all CSS inlined, Google Fonts via `` (only allowed external resource) -- **Interactive** — working hover states, transitions, animations (vanilla JS only) -- **Responsive** — looks good from 375px to 1440px -- **Realistic** — looks like a real product, not a code demo -- **Accessible** — all animations support `prefers-reduced-motion` - ---- - -# DESIGN-ONE MODE - -Design a single targeted piece — only the tokens, states, and animation it needs — from the token source selected in Mode Detection. The process is identical across sources; only the source, preview file, spec output, and STATUS differ (see the table above). - -### Process -1. **Determine the token source** and load its tokens (scratch = none; otherwise read the theme/design-system/brand file). For the **brand** source, read BRAND.md and all existing component specs first; for **project theme**, scan the config/CSS files and extract palette, typography, spacing, effects, component patterns. -2. **Parse** what to design, mood/direction, constraints, context. -3. **Search only what's missing.** Scratch needs style + color (+`--mood` for themes) + animation + ux; the other three sources already supply colors/fonts, so search animation + ux (+ stack-specific guidance for project theme) only. -4. **Generate the preview HTML** at the source's preview file, using the source's tokens (scratch invents new ones; project-theme uses the project's ACTUAL tokens/classes so it looks indistinguishable from existing components). Show all states (default, hover, active, focus, disabled), light AND dark mode, and 2-3 size variants if applicable. -5. **Write/append the spec** per the table (see the output-templates reference for the exact skeleton: Component Spec, Harmonized Component Spec, Extension spec, or Brand Component Spec). Use existing tokens wherever possible; list "New Tokens Needed" only when genuinely required. -6. **If this piece changes shared tokens** (a color, font, spacing, or a component spec other pages inherit), persist it to the live system: `python3 search.py "" --design-system --persist --output-dir docs [--page ]` (see [Live Design System](#live-design-system-docsdesign-system)). A purely one-off component that touches nothing shared does not need to persist. -7. **Return** the source's STATUS. - -Before step 1, honor the read-first rule from [Live Design System](#live-design-system-docsdesign-system): read `docs/design-system/MASTER.md` (and `pages/.md` if working on a page) and design within it. - ---- - -# GENERATE MODE - -Produce N self-contained HTML directions at once. Two targets share the first half; they differ in count, output location, and what happens after. - -### Shared steps -1. **Search the design DB** across all relevant domains: styles (10), palettes (10), fonts (8), animations (10), Google Fonts (10). For animation-heavy features, search multiple animation categories (text, scroll, hover, background, hero, card, chart, button). -2. **Plan N distinct directions.** Assign each a unique combination. **Diversity rules:** no shared style family, primary color, or heading font; alternate light/dark; vary animation complexity, layout, and mood. -3. **Generate N self-contained HTML files**, each placing the component/feature in a realistic page context. - -### Target: showcase (standalone variations) -- Default N = 8. Output `.devline/showcases/01-[style].html` … `N-[style].html`. -- Generate a gallery `index.html` at `.devline/showcases/index.html` linking all variations. -- **Return** `STATUS: SHOWCASES_READY` with a summary table (style, colors, font, animation, theme per showcase). - -### Target: pipeline (brainstorm → design system) -1. **Analyze spec:** Read `.devline/brainstorm.md` — product type, audience, UI scope, platform, aesthetic direction. Use `NEEDS_INPUT` if critical info is missing. Check existing context (design systems, colors, fonts) — recommendations must stay consistent with existing identity. -2. **Search:** run `design_system.py` first, then the shared search above (default N = 3 previews). -3. **Generate N previews** in `.devline/previews/option-01-[style].html`, each meaningfully different, using realistic layouts matching the feature. **Return** `STATUS: NEEDS_INPUT` with Preview Selection. -4. **After selection — apply design reasoning:** match to context, resolve conflicts with the existing codebase, filter anti-patterns, apply priority ordering, add stack-specific guidance. -5. **Select design rules** from `${CLAUDE_SKILL_DIR}/references/design-rules.md` — always Accessibility (P1), Touch (P2), Style (P4), Animation (P7); conditionally Performance (P3), Layout (P5), Typography (P6), Forms (P8), Navigation (P9), Charts (P10). -6. **Write** `.devline/design-system.md` (see output-templates reference); keep `.devline/previews/` for reference. -7. **Persist the live system:** run `python3 search.py "" --design-system --persist --output-dir docs` (see [Live Design System](#live-design-system-docsdesign-system)) so the durable source of truth lands at `docs/design-system/MASTER.md`. **Return summary:** product type, style direction, palette, typography, anti-patterns, design-rule categories included, paths to `.devline/design-system.md` and `docs/design-system/MASTER.md`. - ---- - -# BRAND-INIT MODE - -Create a persistent brand identity at `design-system/` that survives pipeline cleanup. (Adding components to an existing brand is **design-one** with the brand token source.) - -**Principles:** single source of truth (`BRAND.md`), incremental growth, consistency enforcement, additive only. - -### Process -1. **Understand:** product type, mood, audience, requirements, platform. Use `NEEDS_INPUT` if vague. -2. **Search:** full multi-domain search (product, style, mood, typography, animation). -3. **Generate 3 preview options** at `.devline/brand-previews/`, each a different brand direction on a realistic page layout. **Return** `STATUS: NEEDS_INPUT` with Preview Selection. -4. **After selection:** write `design-system/BRAND.md` + 4 initial component specs (button, card, input, badge) to `design-system/components/` (see output-templates reference). -5. **Persist the live system:** run `python3 search.py "" --design-system --persist --output-dir docs` (see [Live Design System](#live-design-system-docsdesign-system)) to establish `docs/design-system/MASTER.md` as the corrections-aware source of truth. -6. **Clean up** `.devline/brand-previews/` and **return** `STATUS: BRAND_CREATED`. diff --git a/agents/references/frontend-output-templates.md b/agents/references/frontend-output-templates.md deleted file mode 100644 index 8b5317f..0000000 --- a/agents/references/frontend-output-templates.md +++ /dev/null @@ -1,338 +0,0 @@ -# Frontend Planner — Output Templates - -Fill these skeletons and write them to the paths shown. Four tables recur across skeletons — they are defined ONCE here as **canonical**; each skeleton names the subset/delta it uses instead of repeating them. - -## Canonical Tables - -### Semantic Color Palette (16 roles) -| Role | Light | Dark | Usage | -|------|-------|------|-------| -| Primary | #xxx | #xxx | Interactive elements, CTAs, links | -| On Primary | #xxx | #xxx | Text/icons on primary | -| Secondary | #xxx | #xxx | Supporting elements | -| On Secondary | #xxx | #xxx | Text/icons on secondary | -| Accent | #xxx | #xxx | Highlights, badges, notifications | -| On Accent | #xxx | #xxx | Text/icons on accent | -| Background | #xxx | #xxx | Page background | -| Foreground | #xxx | #xxx | Default text | -| Card | #xxx | #xxx | Card/panel surfaces | -| Card Foreground | #xxx | #xxx | Text on cards | -| Muted | #xxx | #xxx | Disabled, secondary surfaces | -| Muted Foreground | #xxx | #xxx | Secondary/placeholder text | -| Border | #xxx | #xxx | Borders, dividers | -| Destructive | #xxx | #xxx | Error, danger | -| On Destructive | #xxx | #xxx | Text on destructive | -| Ring | #xxx | #xxx | Focus rings | - -Deltas: **Brand identity** adds two rows — Success and Warning (Light/Dark/Usage). A **color-theme** spec uses a 12-role subset (Primary, On Primary, Secondary, On Secondary, Accent, Background, Foreground, Card, Muted, Border, Destructive, Ring). A **component** spec uses only the component-scoped tokens it needs (see Component Spec). The **design-system** doc lists these roles single-mode as `| Role | Hex | Usage |`. - -### States & Variants -| State | Background | Border | Text | Shadow | Transform | -|-------|-----------|--------|------|--------|-----------| -| Default | ... | ... | ... | ... | — | -| Hover | ... | ... | ... | ... | translateY(-1px) | -| Active | ... | ... | ... | ... | translateY(0) | -| Focus | ... | ... | ... | ring | — | -| Disabled | ... | ... | ... | none | — | - -### Motion & Animation -| Pattern | Duration | Easing | Usage | -|---------|----------|--------|-------| -| Hover lift | 200ms | ease-out | Cards, buttons | -| Press | 150ms | ease-in | Active state | -| Fade in | 200ms | ease-out | Appearing elements | -| Slide in | 300ms | ease-out | Panels, drawers | -| Stagger | 50ms per item | ease-out | Lists, grids | - -**Reduced motion:** all animations collapse to opacity-only or instant transitions. - -### Contrast Verification -| Pair | Light Ratio | Dark Ratio | WCAG AA | WCAG AAA | -|------|------------|------------|---------|----------| -| Foreground / Background | X:1 | X:1 | PASS/FAIL | PASS/FAIL | -| On Primary / Primary | X:1 | X:1 | PASS/FAIL | PASS/FAIL | - ---- - -## Component Spec (`.devline/component-spec.md`) - -```markdown -# Component Spec: [Component Name] - -**Type:** [button / color-theme / menu / card / etc.] -**Generated:** [date] - -## Color Tokens -[ONLY the component-scoped tokens this component needs — not the full palette] - -| Token | Light | Dark | Usage | -|-------|-------|------|-------| -| --component-bg | #xxx | #xxx | Background | -| --component-fg | #xxx | #xxx | Text/icons | -| --component-border | #xxx | #xxx | Border | -| --component-hover | #xxx | #xxx | Hover state | -| --component-active | #xxx | #xxx | Active/pressed | -| --component-focus-ring | #xxx | #xxx | Focus ring | - -## Typography -[Only if relevant] Font: [name] — [why] | Size / Weight / Line-height: [values] - -## States & Variants -Canonical States & Variants table (above). - -## Animation -Canonical Motion & Animation table (above) — list only the patterns this component uses. Library: [CSS only / Motion / etc.]. Reduced motion: [fallback]. - -## CSS Implementation -[Complete CSS with all states, using the tokens above] - -## Accessibility -- Touch target: [size] | Focus indicator: [description] | ARIA: [attributes] | Contrast: [ratio per text/bg pair] - -## Preview -Open `.devline/component-preview.html`. -``` - -## Color Theme Spec (alternative component-spec format) - -```markdown -# Color Theme: [Theme Name] - -**Mood:** [description] -**Generated:** [date] - -## Palette -Canonical Semantic Color Palette (above), 12-role subset. - -## Contrast Verification -Canonical Contrast Verification table (above). - -## CSS Variables -​```css -:root { /* Light */ } -.dark { /* Dark */ } -​``` - -## Tailwind Config -​```js -[Tailwind theme extension] -​``` -``` - -## Harmonized Component Spec (`.devline/component-spec.md`) - -```markdown -# Harmonized Component: [Name] - -**Fits within:** [project name / detected framework] -**Generated:** [date] - -## Project Theme Reference -[Summary of the project's visual identity] - -## Component Design -[Spec using the project's existing tokens] - -### Using Project Tokens -| Element | Token/Class | Value | Source | -|---------|------------|-------|--------| -| Background | var(--card) / bg-card | #xxx | tailwind.config.ts | -| Text | var(--foreground) / text-foreground | #xxx | globals.css | - -### New Tokens Needed -[ONLY if the component requires something not in the project's theme — ideally empty] - -### States & Animation -Canonical States & Variants + Motion & Animation tables (above), using the project's existing transition timing and patterns. - -### CSS / Component Code -[Uses existing project tokens exclusively] - -## Preview -Open `.devline/harmonize-preview.html`. -``` - -## Extension Spec (appended to `.devline/design-system.md`) - -```markdown ---- - -## Extension: [Component Name] -**Added:** [date] - -### New Tokens -[ONLY tokens that don't already exist] -| Token | Value | Usage | - -### Component Spec -States/variants and CSS — canonical States & Variants table (above), using existing tokens where possible. - -### Animation -Canonical Motion & Animation table (above) — new pattern if needed, else reference an existing one. - -### Integration Notes -[How this connects to existing components] -``` - -## Brand Identity (`design-system/BRAND.md`) - -```markdown -# Brand Identity: [Project Name] - -**Created:** [date] | **Last Updated:** [date] -**Product Type:** [category] | **Platform:** [web/mobile/desktop] — [framework] - -## Brand Personality -[2-3 sentences] - -## Style Direction -**Primary Style:** [name] — [rationale] | **Secondary Style:** [complement/contrast] - -## Color System -### Semantic Tokens -Canonical Semantic Color Palette (above), all 16 roles, PLUS two brand rows: -| Success | #xxx | #xxx | Success states | -| Warning | #xxx | #xxx | Warning states | - -### Contrast Verification -Canonical Contrast Verification table (above). - -### CSS Variables -​```css -:root { --primary: [hsl]; /* ... */ } -.dark { --primary: [hsl]; /* ... */ } -​``` - -### Tailwind Config -​```js -colors: { primary: 'hsl(var(--primary))', /* ... */ } -​``` - -## Typography -**Heading / Body / Mono Font:** [name] — [mood, weight range] each - -### Type Scale -| Level | Size | Weight | Line Height | Letter Spacing | Usage | -|-------|------|--------|-------------|----------------|-------| -| Display | 3rem | 700 | 1.1 | -0.02em | Hero headings | -| H1 | 2.25rem | 700 | 1.2 | -0.01em | Page titles | -| H2 | 1.875rem | 600 | 1.3 | 0 | Section headings | -| H3 | 1.5rem | 600 | 1.4 | 0 | Subsections | -| H4 | 1.25rem | 600 | 1.4 | 0 | Card headings | -| Body | 1rem | 400 | 1.6 | 0 | Paragraph text | -| Small | 0.875rem | 400 | 1.5 | 0 | Captions, labels | -| Tiny | 0.75rem | 500 | 1.4 | 0.02em | Badges, overlines | - -### Google Fonts Import -​```css -@import url('[url]'); -​``` - -## Spacing System -| Token | Value | Usage | -|-------|-------|-------| -| --space-1 | 0.25rem | Tight gaps, icon padding | -| --space-2 | 0.5rem | Inline spacing | -| --space-3 | 0.75rem | Form element padding | -| --space-4 | 1rem | Standard padding | -| --space-6 | 1.5rem | Card padding, section gaps | -| --space-8 | 2rem | Section padding | -| --space-12 | 3rem | Large section margins | -| --space-16 | 4rem | Page section spacing | - -## Border & Radius -| Token | Value | Usage | -|-------|-------|-------| -| --radius-sm | [value] | Buttons, inputs, badges | -| --radius-md | [value] | Cards, panels | -| --radius-lg | [value] | Modals, large containers | -| --radius-full | 9999px | Avatars, pills | - -## Shadow System -| Token | Value | Usage | -|-------|-------|-------| -| --shadow-sm | [value] | Subtle lift | -| --shadow-md | [value] | Cards, dropdowns | -| --shadow-lg | [value] | Modals, floating elements | - -## Motion & Animation -**Library:** [CSS only / Motion / GSAP] | **Base timing:** [e.g., 200ms ease-out] -Canonical Motion & Animation table (above). - -## Anti-Patterns -[Product-specific anti-patterns from reasoning rules] - -## Component Index -- [Button](components/button.md) · [Card](components/card.md) · [Input](components/input.md) · [Badge](components/badge.md) -``` - -## Brand Component Spec (`design-system/components/[name].md`) - -```markdown -# [Component Name] - -**Brand reference:** [design-system/BRAND.md] -**Created:** [date] - -## Variants -[List all variants with token mappings] - -## States -Canonical States & Variants table (above), with cells referencing BRAND.md tokens (e.g. Default bg = var(--primary), text = var(--on-primary), shadow = var(--shadow-sm)). - -## Sizes -| Size | Padding | Font Size | Min Height | Icon Size | -|------|---------|-----------|------------|-----------| - -## CSS Implementation -[All tokens reference BRAND.md variables] - -## Brand Compliance -- [x] Uses only tokens from BRAND.md -- [x] Hover timing matches brand motion pattern -- [x] Border radius uses brand token -- [x] Focus ring uses brand Ring token -``` - -## Design System (`.devline/design-system.md`) - -```markdown -# Design System — [Feature Name] - -**Product Type:** [matched category] | **Platform:** [web/mobile/desktop] — [framework] -**Generated:** [date] - -## Style Direction -**Primary Style:** [name] — [why] | **Secondary Style:** [complement] | **Layout Pattern:** [recommended] - -## Color Palette -Canonical Semantic Color Palette (above), 16 roles, single-mode: `| Role | Hex | Usage |`. -**Color Mood:** [from reasoning rules] | **Notes:** [contrast, WCAG compliance] - -## Typography -**Heading / Body Font:** [names] | **Google Fonts Import:** `@import url('[url]');` | **Tailwind Config:** [font config] - -## Key Effects -[Animation and transition recommendations] - -## Animated Components -**Motion Library:** [recommended] -| Component | Category | Trigger | Library | Complexity | Mobile | -|-----------|----------|---------|---------|------------|--------| - -## Anti-Patterns -[Product-specific] - -## Common UI Issues -| Rule | Do | Avoid | -|------|----|-------| - -## Design Rules -[Only relevant priority categories for this feature] - -## Stack-Specific Guidelines -[Framework-specific UX guidelines] - -## Pre-Delivery Checklist -[Visual quality, interaction, light/dark, layout, accessibility checks] -``` diff --git a/skills/design/CREDITS.md b/skills/design/CREDITS.md new file mode 100644 index 0000000..754bcc9 --- /dev/null +++ b/skills/design/CREDITS.md @@ -0,0 +1,18 @@ +# Credits + +The design skill adapts ideas and text from these sources. Everything except `references/web/` is paraphrased and rewritten for devline; `references/web/` holds unchanged copies. + +| Source | Licence | Used in | +|---|---|---| +| [Impeccable](https://github.com/pbakaus/impeccable) by Paul Bakaus | Apache-2.0 | antipatterns, craft-floor, seeds (concept roll), verbs (commands), rubric (critique), slop-scan rules | +| [frontend-design](https://github.com/anthropics/skills/tree/main/skills/frontend-design) by Anthropic | Apache-2.0 | antipatterns, slop-scan rules | +| [unslop](https://github.com/heydamir/unslop) by Damir Sokolovsky | CC BY 4.0 | antipatterns, craft-floor, slop-scan rules (signs list) | +| [Emil Kowalski's skills](https://github.com/emilkowalski/skills) | MIT | antipatterns, craft-floor, motion, verbs | +| [gsap-skills](https://github.com/greensock/gsap-skills) by GreenSock | MIT | motion | +| [threejs-skills](https://github.com/CloudAI-X/threejs-skills) by CloudAI-X | MIT | motion | +| [r3f-skills](https://github.com/EnzeD/r3f-skills) | no licence stated; ideas only, paraphrased | motion | +| [web-interface-guidelines](https://github.com/vercel-labs/web-interface-guidelines) by Vercel | MIT | craft-floor | +| [charles-skills](https://github.com/LemonFace0309/charles-skills) (polish, unreasonable craft) | no licence stated; ideas only, paraphrased | rubric (polish scoring), seeds | +| [Modern Web Guidance](https://github.com/GoogleChrome/modern-web-guidance) v1.0.0 (4dd9683) by Google Chrome | Apache-2.0 | `references/web/*.md`, copied unchanged from `skills/modern-web-guidance/guides/`; licence text in `references/LICENSE-APACHE` | + +`signature.md`, `mockup.md` and `design-system.md` are written for devline. diff --git a/skills/design/SKILL.md b/skills/design/SKILL.md index 5d7f134..31ffbf3 100644 --- a/skills/design/SKILL.md +++ b/skills/design/SKILL.md @@ -1,117 +1,69 @@ --- name: design -description: Standalone design skill for individual components, color themes, brand identity, or fitting within an existing project theme. Use when the user asks to "design a button", "create a color theme", "create a brand identity", "make this match our site", "show me 6 card styles", "add a modal to the brand", or any targeted UI design request. Also triggers on mood-based requests like "warm dark theme", "cool minimalist colors", "playful typography". -argument-hint: "" +description: Design distinctive, crafted interfaces from real content instead of the default AI look, and build cheap interactive mockups of anything. Use when the user asks to design a page, site, app screen, widget or design system ("design the homepage", "explore directions for…", "redesign this UI"), or to mock something up ("mock up the new edit mode", "make a mockup of the battery widget"). +argument-hint: "[mockup] " user-invocable: true disable-model-invocation: false --- -# Design — Standalone UI Design +# Design -Launch the **frontend-planner** agent for targeted design work outside the full devline pipeline. +Two modes, one **designer** agent that does one step per launch: +- **Exploration** (default): new looks for a page, site or app. Many cheap sketches, a critic culls, the user picks, only the picks become full prototypes, then refine against rendered captures until they score 8+. +- **Mockup** (`mockup `, or any request that says "mockup"/"mock up"): one cheap, interactive HTML mockup of exactly the surface a change touches. See `references/mockup.md`. -## What You Do +Nobody scores their own work: every critique is a fresh designer launch that sees only captures. -Parse the user's request, detect the right mode, and launch the frontend-planner agent with a clear prompt. You are a router, not a designer. - -## Mode Detection - -The frontend-planner has three modes. Route the request to one — and for `design-one`, also pick the token source: - -| Mode | Trigger | Example | -|------|---------|---------| -| **brand-init** | First-time persistent brand identity (no `design-system/BRAND.md` yet) | "create a brand identity", "set up our brand" | -| **generate** | Multiple directions at once — a full design system, or N showcase variations | "create a design system for a fintech app", "show me 8 button styles" | -| **design-one** | A single element from one token source (see below) | "design a button", "add a modal to the brand", "match our site" | - -**design-one — pick the token source:** - -| Token source | Trigger | -|--------------|---------| -| **brand** | `design-system/BRAND.md` exists + adding an element ("add a table to the brand") | -| **project-theme** | Fit the project's existing theme ("match our site", "our current colors") | -| **design-system** | `.devline/design-system.md` exists + new element ("add a modal that fits our system") | -| **scratch** | Standalone piece, no existing system ("design a dark button", "warm earth palette") | - -**Priority order when ambiguous:** -1. `design-system/BRAND.md` exists and the request adds a component → **design-one** (brand) -2. "match", "fit", "our site", "current theme" → **design-one** (project-theme) -3. "brand", "identity", "persistent" and no `BRAND.md` → **brand-init** -4. A count ("8 buttons", "6 cards") → **generate** (showcase) -5. "design system for [product]" → **generate** (pipeline) -6. `.devline/design-system.md` exists → **design-one** (design-system) -7. Default → **design-one** (scratch) - -## Execution - -Launch the **frontend-planner** agent with the mode — and for design-one, the token source. - -### brand-init: -``` -Mode: brand-init - -Brand request: [user's request] -Product context: [any product/mood/industry context] -Platform: [if mentioned] - -Create the brand identity system at design-system/BRAND.md with initial component specs. +This skill's base directory (shown above as "Base directory for this skill") holds `references/` and `scripts/`. Pass the absolute `references/` path to every launch as `References:`. You run the scripts yourself: +```bash +node /scripts/capture.mjs --sheet --frames --video scroll # web page +node /scripts/capture.mjs --narrow 420 --video script --demo # app UI, widget, mockup +node /scripts/capture.mjs --stills-only # sketch +node /scripts/slop-scan.mjs > /slop.json +python3 -I /scripts/gallery.py "" ``` - -### generate (pipeline — full design system): +capture needs playwright-core in `~/.cache/devline/capture`. If it's missing, ask before installing (about 150 MB): `npm i --prefix ~/.cache/devline/capture playwright-core && node ~/.cache/devline/capture/node_modules/playwright-core/cli.js install chromium`. Without it, the critic judges from the HTML only and the report says so. + +## Settings +Read `.claude/devline.local.md` (repo), then `~/.claude/devline.local.md` (user); the repo wins. All keys optional: +- `design_model` (default `opus`), `mockup_model` (default `sonnet`) +- `design_sketches` (default 10), `design_pick`: `ask` (default) | `auto` +- `design_mode`: `auto` (default) | `m3e-strict` | `default` + +**Precedence for counts and who picks:** the user's request (a number, "you pick", "just build three") > settings > ask when it isn't obvious. Never override an explicit instruction in the request. + +## Inputs (both modes) +- **Facts**: the real content (files, a facts file, the project itself). Never invent content. +- **Taste brief**: loves, dislikes, musts, references. Ask briefly if absent and not inferable. +- **Target**: `web page` | `app UI` (desktop window 1440x900 + narrow ~420) | `component/widget` (real size, in its real context). +- **Mode**: `m3e-strict` when `design_mode` says so, the user asks for M3E, or the project uses Material 3 Expressive (M3E tokens or components in the code, an M3E theme, docs or a design system naming it). Strict mode needs the `kb-m3e` skill: pass its absolute `references/` path as `M3E:` (`<base>/../kb-m3e/references`). If that directory doesn't exist, stop and tell the user strict mode needs the kb-m3e skill; never fall back to remembered M3E values. Otherwise `default`. +- **Design system**: if `docs/design-system/MASTER.md` exists, pass it; its Corrections section is binding. See `references/design-system.md`. + +## Exploration loop (work dir `.devline/design/`) +1. **Seeds**: one launch, `Step: seeds` → `seeds.md` with `design_sketches` seeds per `seeds.md`. +2. **Sketch**: one launch per seed, **all in one message**, `Step: sketch` → `sketches/s<k>.html` + `sketches/s<k>.story.md`. Cheap: a finished first screen and a storyboard; no 3D or interaction code. +3. **Capture** each sketch with `--stills-only` into `captures/s<k>/`. +4. **Cull**: one fresh launch, `Step: cull`, all capture folders and story files → `cull.md`: drops weak, generic and sibling sketches, keeps 4-8 ranked (fewer only if fewer deserve it), each with the quality to protect. +5. **Pick**: build the sketch gallery (`gallery.py .devline/design sketches captures "Sketches"`), give the user the serve command (`cd <abs>/.devline/design/gallery && python3 -m http.server 8092`) and ask which to build with AskUserQuestion (multi-select over the kept sketches, usually 2-4). With `design_pick: auto` or a request that delegates the choice, take the top 3 from `cull.md`. +6. **Build**: one launch per pick, in parallel, `Step: build` → `final/<k>.html`, plus `final/<k>.demo.json` for app UIs and widgets: the full working prototype. +7. **Capture** each (web: `--sheet --frames --video scroll`; app UI: `--narrow 420 --video script --demo final/<k>.demo.json`) + slop scan into `captures/final/<k>/`. +8. **Critique**: one fresh launch per design, `Step: critique` → `critique-<round>-<k>.md` with Wow and Craft scores and the next verb(s) or `done`. +9. **Refine**: `Step: refine` with the critic's verb(s), same output path; then 7-8 again. Stop per design at `done` (both scores ≥ 8, nothing high), after 3 refine rounds, or when neither score moved in two rounds. +10. **Report**: rebuild the gallery over `final/` (`gallery.py .devline/design final captures/final "Final"`). Per design: path, Wow/Craft, the screenshot-worthy moment, assumptions, and in strict mode the decisions taken where the spec allowed. Ask with AskUserQuestion which one to take forward unless the request already said; record the answer and feedback verbatim in `.devline/design/feedback.md`. On approval, write `docs/design-system/MASTER.md` from the chosen design per `design-system.md`. + +## Mockup flow +1. `Step: mockup` launch (model `mockup_model`) with the request verbatim, the project root (if any), facts, taste, the M3E path in strict mode, and `Output:` (as the user gives it; else `.devline/mockups/<slug>.html`). It writes the mockup and `<slug>.demo.json`. +2. Capture it (`--narrow 420 --video script --demo <slug>.demo.json`; pages: `--video scroll`) + slop scan. One `Step: mockup` fix pass for anything broken (page errors, a broken state, a high slop hit). A critique only if the user asked (`--critique`). +3. Report the path, how to open it, and what works in it. Each later change request: `Step: mockup` with `Input:` = the same file and the request verbatim; the designer appends to `<slug>.feedback.md` and re-reads it before every edit. + +## Launch prompt ``` -Mode: generate -Variant: pipeline - -Product context: [user's description] -Platform: [if mentioned, otherwise ask] - -No brainstorm file exists — use this description directly as the product context. Write the full design system to .devline/design-system.md. +Step: seeds | sketch | cull | build | refine | critique | mockup +References: <abs path> M3E: <abs path, strict mode only> +Mode: default | m3e-strict Target: web page | app UI | component/widget +Facts: <path(s)> Taste: <path or inline> Design system: <MASTER.md path or none> +Seed: <k> Input: <file> Verbs: <refine> Critique file: <refine> +Captures: <folder(s)> Request: <verbatim, mockup> Project: <root, mockup> +Output: <path> ``` - -### generate (showcase — N variations): -``` -Mode: generate -Variant: showcase - -Component: [what to showcase] -Count: [N from request, default 8] -Constraints: [any constraints mentioned] - -Output showcases to .devline/showcases/ -``` - -### design-one: -If the token source is `brand` or `design-system`, first verify `design-system/BRAND.md` / `.devline/design-system.md` exists. Then launch: -``` -Mode: design-one -Token source: [scratch | project-theme | design-system | brand] - -Design request: [user's request] -Context: [product/mood/constraints — or the existing brand/system/theme to read tokens from] - -Read the token source first (if any), then output the spec to .devline/component-spec.md and preview to .devline/component-preview.html. For the brand source, add the component under design-system/ and update BRAND.md. -``` - -## After Agent Completes - -Report the result to the user: -- **brand-init**: "Brand identity at `design-system/BRAND.md` with N component specs. Add more: `/design add [component] to the brand`" -- **generate (pipeline)**: "Design system at `.devline/design-system.md`" -- **generate (showcase)**: "N showcases at `.devline/showcases/`, open `index.html` for the gallery" -- **design-one**: "Component spec at `.devline/component-spec.md`, preview at `.devline/component-preview.html`" (brand source: component added under `design-system/`, BRAND.md updated) - -## Rules - -- Do NOT run the full devline pipeline (no brainstorm, no plan, no implementation) -- Do NOT ask unnecessary questions — if the user says "design a dark button", just design it -- Do launch the frontend-planner agent — do not design anything yourself -- If the user's request is ambiguous about mode, follow the priority order above -- `brand-init` and `design-one` (brand source) outputs are PERSISTENT (in `design-system/`) — they survive pipeline cleanup -- All other mode outputs are in `.devline/` and are temporary - -## Live Design System (`docs/design-system/`) - -Beyond the mode outputs above, the frontend-planner maintains one durable, corrections-aware design system per repo at `docs/design-system/` (`MASTER.md` + `pages/<page>.md`). It survives across sessions. The agent: -- **Reads it first** — before designing, it checks `docs/design-system/MASTER.md` (and `pages/<page>.md` for the current page, which overrides MASTER) and works within it, including the `## Corrections & Decisions` log, so past mistakes aren't repeated. -- **Persists on generate** — establishing or changing the shared system writes/regenerates `docs/design-system/` (via `search.py --design-system --persist --output-dir docs`). -- **Persists on correction** — when you correct a design or a choice fails, it appends a dated bullet to `## Corrections & Decisions` (MASTER for global, the page file for page-specific) and updates the affected spec. Nothing is lost between sessions. +Launch the designer with `model:` from settings: `design_model` for exploration steps, `mockup_model` for mockups. diff --git a/skills/design/references/LICENSE-APACHE b/skills/design/references/LICENSE-APACHE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/skills/design/references/LICENSE-APACHE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/skills/design/references/antipatterns.md b/skills/design/references/antipatterns.md new file mode 100644 index 0000000..c322ded --- /dev/null +++ b/skills/design/references/antipatterns.md @@ -0,0 +1,63 @@ +# Antipatterns: the AI look, why it fails, what to do instead + +Sources: Anthropic frontend-design (Apache-2.0), Impeccable craft floor (Apache-2.0), unslop by Damir Sokolovsky (CC BY 4.0), Emil Kowalski (MIT). Paraphrased. + +Every item below is a default, not a choice: it appears whatever the subject is. The brief's own words can ask for any of them; a free axis must never be spent on one. When you find one, rewrite the element, don't soften it. + +## The five current clusters (check the whole plan against these first) +1. Warm cream ground (~#F4F1EA) + high-contrast serif display + terracotta/clay accent (~#D97757). +2. Near-black ground with one acid-green, vermilion or neon accent, often with glow. +3. Broadsheet: hairline rules everywhere, zero radius, dense newspaper columns. +4. SaaS card kit: content chopped into identical rounded cards, one radius on everything, the same soft grey shadow, gradient washes. +5. Template chrome: tracked ALL-CAPS eyebrow above every heading, `A · B · C` meta strings, `WORD — fragment` labels, #0B0B0B/#111 as black, monospace for small labels, `→` appended to buttons. + +## Layout and structure +| Default | Why it fails | Instead | +|---|---|---| +| Hero = big headline + subtext + two buttons, centered | Every template | Open with the most characteristic thing in the subject's world (an object, a live demo, a process, a scene) | +| Hero metric block (huge number, small label, side stats, accent) | The commonest "data" costume | A number only where it is the point, with its denominator | +| Three equal feature cards (icon + heading + text) | Lazy container, says nothing | Structure from the content: a sequence, a comparison, a map, a ledger | +| Nested cards, border + wide shadow pairs, colored side stripes | Noise as hierarchy | One depth cue per surface; space shows grouping | +| Section numbers 01/02/03 | Only true for real sequences | Number only a real sequence | +| Eyebrow/kicker above a heading | Ban. The heading carries its weight | Delete it | +| Everything centered | Template default | Left-aligned reading edge; center only short lines or a device frame | +| Modal for something that can open in place | Interrupts for nothing | Disclose in place | +| Bento grid of mixed tiles as the page | 2024 Apple-pastiche | Only when the content really is a set of unequal items | + +## Surface +| Default | Why | Instead | +|---|---|---| +| Purple/blue gradients, gradient text, gradient borders | The canonical AI tell | Color from the subject's world; emphasis from size/weight | +| Glassmorphism, backdrop blur as decoration | Costume | Blur only where something really sits over content (a sheet over a page) | +| Glows, radial halos, colored shadows, neon borders | Decoration that competes with content | Neutral soft shadow with offset, or none | +| Grain/noise overlays, dot grids, line grids, aurora blobs, orbs, floating shapes | Filler that says nothing | A real material or a real object from the world, or nothing | +| Pills (999px) on every button/tag | Uniformity, not design | Radius by hierarchy; inner = outer - padding | +| Emoji or unicode glyphs as icons (✨ → ↗ ✓) | Cheap and inconsistent | One drawn SVG set, one stroke weight | +| Shape-assembled fake illustrations, stock-photo stand-ins | Lies about the product | Real assets, honest diagrams, or rendered objects | +| Light/dark picked by category ("tech = dark") | Not a decision | Pick from the use scene and the world | + +## Type +| Default | Why | Instead | +|---|---|---| +| Inter, Roboto, Arial, system UI as display; Space Grotesk, DM Sans, Plus Jakarta, Instrument Sans/Serif, Geist, Fraunces, Playfair, Newsreader as reflex picks | The faces every model reaches for | Choose for the character; look past the first page of Google Fonts; one family or two clearly distinct ones | +| Italic or colored accent on one word of a headline | Commonest typographic tell | Let the whole line carry it, or change the sentence | +| ALL-CAPS tracked labels, mono labels as "technical" costume | Template chrome | Sentence case; mono only for code, data, measurement | +| 700-900 weight everywhere, tight tracking on small text | Shouting | Scale and color for hierarchy; tracking only on display sizes | + +## Motion +| Default | Why | Instead | +|---|---|---| +| Fade-and-slide-up on every section, staggered | The single most recognisable AI motion | One authored moment; most content is simply there | +| Identical hover lift on every card | Says nothing | Hover only where it tells the user something, inside `@media (hover:hover)` | +| 3D tilt cards, magnetic buttons, custom cursors, cursor trails, spotlight-follow | Toy effects | Motion that answers a question (where did this come from, what changed, what comes next) | +| Count-up numbers, typewriter, text scramble, glitch | Delays content for show | Show the number; animate only the delta when it changes | +| Bounce/elastic easing, springs on everything | Wobble | One easing family; bounce only for physical, playful things | +| Scroll progress that jumps station to station, timed animation triggered by scroll | Disconnects the hand from the screen | Scroll-linked progress is scrubbed and continuous | +| Things that appear and vanish (ambient layers that come and go) | Feels broken | Ambient layers persist, subordinate, and hand over without an edge | +| Animating keyboard/frequent actions | Feels slow | No animation for things done 100 times a day | + +## Copy +- No slogans, aphorisms, rule-of-three lists, "X. Not Y." rebuttals, punchline headings, hype words (seamless, robust, powerful, unlock, supercharge). +- No invented numbers, testimonials or logos. Use only the facts given. +- Controls name their action; the same action keeps one name. Errors name the problem and the fix, never apologize. +- Headings are plain topic titles unless the brief asks otherwise. diff --git a/skills/design/references/craft-floor.md b/skills/design/references/craft-floor.md new file mode 100644 index 0000000..2ce5eee --- /dev/null +++ b/skills/design/references/craft-floor.md @@ -0,0 +1,38 @@ +# Craft floor + +Build to this without announcing it. It holds the mechanics; it never picks the direction. +Sources: Impeccable craft floor + typeset (Apache-2.0), vercel web-interface-guidelines (MIT), Emil Kowalski (MIT), unslop (CC BY 4.0). Paraphrased. + +## Type +- One family, or two clearly distinct ones (plus mono only for code/data). Sizes from a deliberate scale; at most ~5 text sizes per screen, display counted separately. +- Body measure 45-75ch; body leading 1.4-1.6 (serif a little more); display leading 0.9-1.1; display max ~6rem on desktop, `clamp()` down to phones. +- Tracking: none below ~28px; slightly negative only on display (floor -0.04em). +- `text-wrap: balance` on headings, `pretty` on prose. Typographic quotes and apostrophes. Tabular, lining numerals for figures that change or align. +- Theme the browser surfaces: `::selection`, caret, focus ring, scrollbar, underline offset. + +## Space and layout +- One spacing scale (4px base). Tight inside groups, generous between them; more space above a heading than below. +- At most ~3 dominant vertical alignment lines per breakpoint. Icons on a spine, text on an edge. +- Radius by hierarchy, inner = outer - padding. One depth cue per surface. +- Works at 375, ~1024 and 1440 wide: adapted, not shrunk. Check 1000-1100 px for overflow. + +## Color and contrast +- Palette from the world: 4-6 named values. Neutrals tinted toward the world; one accent used rarely. +- Contrast computed, not guessed: body ≥4.5:1, large text and icons ≥3:1, **control borders ≥3:1 against every background they sit on**, text over images/canvas measured over the real backdrop. +- Never convey state by color alone. + +## Interaction and states +- Hit targets ≥40px desktop, ≥44px touch (pseudo-element if the visual is smaller). Action links people must notice are real buttons: icon + label, one primary per section. +- Visible `:focus-visible` ring, neutral, never clipped by `overflow`/masks; keyboard reaches everything in visual order. +- Hover inside `@media (hover: hover)`, named properties, ~150ms, no layout change, no `transition: all`. +- Press feedback `scale(.97)`; enter from `scale(.95)` + opacity, never from 0. +- Design every state that the content implies: empty, loading, error, offline/unreachable, no JS, no WebGL, reduced motion. +- Inputs 16px (iOS), real labels, Enter submits. +- `forced-colors` and `prefers-contrast` don't break the page. + +## Content and assets +- Real content only. No placeholder copy, no invented facts, no fake logos or avatars. +- Third-party marks unaltered, with clear space, labelled. +- No content hidden at rest waiting for a script: without JS the page reads fully. +- First paint already correct (theme, fonts loaded with `font-display: swap` and sensible fallbacks); no flash of a wrong state. +- Self-contained file: inline CSS/JS. Allowed externals: Google Fonts, and pinned ES modules from jsdelivr (`three@0.170.0`, `gsap@3.12.5`) when the design needs them. diff --git a/skills/design/references/design-system.md b/skills/design/references/design-system.md new file mode 100644 index 0000000..b0a9ecf --- /dev/null +++ b/skills/design/references/design-system.md @@ -0,0 +1,23 @@ +# Design system: MASTER.md and the Corrections log + +After the user picks a design, its decisions become the project's design system, so later work builds on it instead of redesigning from scratch. + +## Where +`docs/design-system/MASTER.md` in the project (the user may name another path). One file; page-specific additions as sections, not new files. + +## Written from the chosen design +Extract what the approved design actually uses; never regenerate or "improve" it while writing it down. +1. **Concept**: the world, the signature moment, and the "X becomes Y" chain of its transitions. +2. **Tokens**: every colour (with role and the contrast pairs it's checked for), type scale (family, sizes, line heights, weights, tracking), spacing scale, radii, shadows/elevation, motion (easings or springs, durations), breakpoints. Names follow the project's toolkit (CSS custom properties, Tailwind theme, QML singleton, etc.). +3. **Components**: each component in the design with its states (default, hover, focus, pressed, disabled, selected, error, loading, empty) and its motion. +4. **Rules**: what this design never does (its own don't list), reduced-motion behaviour, no-JS/no-WebGL fallbacks. +5. **Acceptance checklist**: the checks every later UI task is verified against (contrast pairs, signature transitions still answer "what becomes the next thing", tokens only, states covered, reduced motion). +6. **Corrections**: append-only, newest last. Each entry: date, what was wrong, the rule now. Binding for every later design or implementation step; never edited or removed except by the user. + +## The tokens rule +Every colour, size, radius, shadow and duration in code comes from a token. No literal values in component code; a value the spec or design needs that has no token yet becomes a new named token first. Reviewers flag literals. + +## Using it +- Exploration and mockup steps read MASTER.md first; the design stays inside it unless the request is to change the design system. +- When the user corrects a design decision, append it to Corrections in the same turn. +- Strict mode (M3E): MASTER.md records only the choices taken where the spec allows, each with its spec reference; spec values themselves are not copied in. diff --git a/skills/design/references/mockup.md b/skills/design/references/mockup.md new file mode 100644 index 0000000..8da5c30 --- /dev/null +++ b/skills/design/references/mockup.md @@ -0,0 +1,44 @@ +# Mockup: cheap, interactive, confined to what matters + +A mockup answers "how will this look and behave?" before the real thing is built. It's cheaper than building the feature and quick to change. It works for anything: a web page, an app screen, a desktop widget, a menu, a dialog, a panel. + +## 1. Scope first +Decide the smallest surface the change needs and mock only that. +- Whatever the change touches **behaves like the real thing**: its clicks, right-clicks, keyboard, hover, drag, open/close, and the transitions between its states. +- Everything around it is **static context** (drawn once, inert) or **absent**. +- Example: a new edit mode for desktop widgets = the desktop with its widgets, the right-click menu, and only the "Edit widgets" entry working; the edit mode itself fully interactive. The rest of the shell isn't mocked; the other menu entries do nothing. +- Example: a new battery widget = the widget in its real place (on the bar or desktop, at real size) and its popout; not the whole bar's other widgets beyond static context. +Write the scope as the first lines of `<slug>.feedback.md`: what's interactive, what's static context. + +## 2. Look like the real thing +- **Inside a project:** read its theme/token files, fonts, icon set, a sibling screen that does something similar, and the UI wording it already uses. Reuse them, so the mockup reads as the app rather than as a web page. Before inventing a control, check whether the project has one; use the existing one. +- Tokens only: colours, sizes, radii, durations come from the project's tokens (declared once as CSS custom properties). A spec value with no token becomes one named property. +- **Strict mode** (project uses M3E): every value from `M3E:`; decisions only where the spec allows. +- **Outside a project:** facts and taste as given; ask briefly if neither says what it should look like. +- Real sizes: a widget at its real size in its real context, a dialog at dialog size, a desktop app at 1440x900 and narrow. + +## 3. Control section +A clearly separated area (visually distinct, outside the mocked surface, e.g. a narrow strip at the edge) holding **only** the inputs that matter for this mockup and can't be changed inside the mocked thing itself: +- environment states (a device has a battery or not, a network is offline, a second monitor is connected), +- settings from a settings page that isn't mocked but changes what's shown, +- theme, when the change has to work in several. +Nothing generic: no switchboard of every state, no design variants unless the user asked to compare options. If something can be changed inside the mocked surface, it's not in the control section. + +## 4. Text +Short labels in the app's own wording. No sentences explaining a control, no notes about what stays or what happens, no header describing the mockup. Sample data looks real (plausible names, values and counts) and includes the case that stresses the layout when it matters (a long name, several devices). + +## 5. Demo script (`<slug>.demo.json`) +So captures show the behaviour: a list of steps the capture tool replays, with a still taken after each. +```json +[{"click": "#desktop", "button": "right"}, {"wait": 400}, {"click": "text=Edit widgets"}, {"wait": 600}, + {"drag": ["#widget-cpu", 120, 40]}, {"press": "Escape"}, {"click": "#ctl-battery"}] +``` +Steps: `click` (selector or `text=…`, optional `button`), `hover`, `press` (key), `type` ([selector, text]), `drag` ([selector, dx, dy]), `scroll` (pixels), `wait` (ms). Cover the main path through the interactive scope and each control-section input once. + +## 6. Iterate in place +Each change request edits the same file. `<slug>.feedback.md` records the scope, then per round the request verbatim and what changed. Read it before every edit; never undo a recorded decision unless the new request says so. Remove what was dropped instead of hiding it. + +## 7. Check before returning +- No page errors; every interactive element in scope responds; nothing outside scope pretends to work beyond static context. +- Text fits at the real size; focus visible; keyboard reaches the interactive scope. +- The control section changes what it claims to change. diff --git a/skills/design/references/motion.md b/skills/design/references/motion.md new file mode 100644 index 0000000..854e291 --- /dev/null +++ b/skills/design/references/motion.md @@ -0,0 +1,41 @@ +# Motion + +Sources: Emil Kowalski skills (MIT), greensock/gsap-skills (MIT), CloudAI-X/threejs-skills (MIT), enzed/r3f-skills (paraphrased, no licence), Modern Web Guidance (Apache-2.0; see `web/`), plus lessons from shipped scroll-driven work. Paraphrased. + +## The qualities (what makes motion feel designed) +1. **Every transition answers "what on screen becomes the next thing?"** Nothing pops in. A new state is something already visible turning into something else: a shape becomes the next frame, a line becomes a border, a dot becomes a node. If nothing carries over, redesign the transition. +2. **Two layers.** The container moves (a scene pins, a frame reshapes) while the content inside keeps living at rest (a value updates, a line draws on, a detail cycles). Nested motion reads as depth. +3. **One physical model.** One light direction, one shadow model, one easing family, one rhythm across the page. +4. **Rhythm: hold, decisive move, hold.** Calm, then a fast eased transition, then calm. Never constant wobble. +5. **The subject's own process is the narrative.** The order of the content is the order of the motion (dusk to dark; source to compiled output; queue to playback). +6. **Type is part of the scene.** Big, short headlines layered with objects; one idea per screen. +7. **Bookends.** It ends where it began, resolved (the opening shape returns as the closing one). +8. **Scroll-scrubbed progress is continuous.** Anything tied to scroll follows every pixel, forwards and backwards. Timed eases are only for discrete events (a click, a state change). Never step from station to station. +9. **Pinned scenes keep moving.** While a section is pinned, the signature element still advances with scroll; nothing freezes. +10. **Ambient layers are subordinate and persistent.** Quieter than the hero, present through every section, handed over without an edge, contrast budget computed against the text over them, paused offscreen and in hidden tabs. +11. **Reduced motion is a designed static state**, not "animations off": same information, final or best frames, nothing hidden. +12. **Nothing decorative touches or overlaps a line or a label.** + +## Should it animate? (ask in order) +1. Frequency: done 100+ times a day or from the keyboard → no animation. Tens of times → minimal. Occasional → standard. Rare/first time → may delight. +2. Purpose: spatial continuity, state change, explanation, feedback, preventing a jarring jump. "Looks cool" on a frequent action → cut. +3. Curve: entering/exiting → strong ease-out (`cubic-bezier(.23,1,.32,1)`); moving on screen → ease-in-out (`cubic-bezier(.77,0,.175,1)`); hover/color → ease, ~150ms; constant → linear; follows a finger or can be interrupted → spring without bounce. `ease-in` alone is never an entrance. +4. Duration: press/hover 100-150ms; tooltip/menu 150-250 (exit 20-30% faster); panel 200-300; page-level 300-400; a one-off choreography ≤2.5s with no dead stretch. Scroll-scrubbed motion has no duration: it is the scroll. +5. Interruptible: input is never locked; reversing aims at the current target; scrubbed scenes fully reversible with no end-of-travel jump. + +## Chooser: which tool +| Need | Use | Notes | +|---|---|---| +| Scroll-linked reveal, progress, parallax-free scrubbing of transform/opacity/clip-path | **CSS scroll-driven animations** (`animation-timeline: scroll()/view()`, `view-timeline`) | Runs on the compositor, no JS, no jank. Feature-detect with `@supports (animation-timeline: view())`; fallback = the static final state. See `web/scrollytelling.md`, `web/scroll-entry-exit-effects.md`. | +| State change within a page or between pages, shared-element morphs | **View Transitions** (`document.startViewTransition`, `view-transition-name`) | Same-document is widely supported; give morphing elements a stable name. See `web/faster-spa-view-transitions.md`. | +| Pinned multi-step scenes, timelines with many coordinated parts, SVG morphs, scrubbing values CSS can't reach | **GSAP + ScrollTrigger** (`gsap@3.12.5` from jsdelivr ESM) | Put the ScrollTrigger on the timeline, not on child tweens; `scrub: true` (or a small number for smoothing); `pin` the scene; `invalidateOnRefresh`; kill on teardown; use `gsap.matchMedia()` for reduced motion and breakpoints. | +| A live 3D subject, scroll-scrubbed camera through a scene, materials and light | **three.js** (`three@0.170.0` via importmap) | One canvas, fixed behind content or pinned. Map scroll to a normalized progress 0..1, damp it (`p += (target - p) * 0.1` per frame), drive camera and scene from the damped value. `renderer.setPixelRatio(Math.min(devicePixelRatio, 1.5))`. Render only when visible and when progress or time changes; pause on `visibilitychange`. Dispose geometries/materials. Reduced motion: render the key frames as static stills. No-WebGL fallback: a static drawn/SVG version. | +| Simple hover/press/disclosure | CSS transitions | Named properties only. | + +Pick the lightest tool that achieves the idea; don't mix GSAP and another JS animation library. Native scroll only: no scroll hijacking, no smooth-scroll libraries that take over the wheel. + +## Performance budget +- Animate `transform`, `opacity`, `clip-path`, `filter` (small blur, never scrubbed); avoid layout properties. `stroke-dashoffset` paints on the main thread: fine for small SVGs, not for full-page lines. +- 60fps target: no long task >50ms during scroll; p95 frame gap ≤20ms. +- DPR cap 1.5 for canvases; keep draw calls low; instancing for repeated meshes; textures power-of-two and small. +- Main-thread scroll handlers only read `scrollY` and write one variable; no layout reads in the loop. diff --git a/skills/design/references/rubric.md b/skills/design/references/rubric.md new file mode 100644 index 0000000..2f7c5a4 --- /dev/null +++ b/skills/design/references/rubric.md @@ -0,0 +1,50 @@ +# Rubric: how the critic scores + +The critic did not build the design and judges only from captures: stills (desktop first view, mid-scroll, an 8-frame scroll sheet, narrow, reduced motion, stills along the demo script), the frame-change list, the slop scan and the page error list. It may open the HTML to check a specific doubt, never to read the designer's intent. +Anchors written for devline, informed by Charles' polish scoring (paraphrased) and Impeccable's critique (Apache-2.0). + +## Two scores, 3-10 each +**Wow**: would someone stop scrolling, screenshot it, copy it? +| Score | Meaning | +|---|---| +| 3 | Looks like everything else (template, AI look) | +| 5 | A clear idea, but it stays on the surface: decoration, not structure | +| 7 | The idea shapes the page and its motion; nothing yet worth a screenshot | +| 8 | One moment people would screenshot, and the motion carries meaning (`signature.md` holds) | +| 9 | That moment holds across the whole page and every width; a rival would copy it | + +**Craft**: does everything that's there work? +| Score | Meaning | +|---|---| +| 3 | Broken states, unreadable text, layout falls apart | +| 5 | Designed at rest; motion, states or narrow layout are default | +| 7 | Every state designed, motion correct, small visible defects | +| 8 | No visible defect at the viewing size; contrast, alignment, rhythm, reduced motion all hold | +| 9 | Holds under stress: long content, odd widths, no WebGL, keyboard only | + +10 is not awarded. **Done** = both ≥ 8 and no high finding. + +## Caps and fails +- No screenshot-worthy moment → Wow ≤ 7. +- **Grounding:** if the subject's name were swapped and it still fit → Wow ≤ 5. +- **Signature claimed but absent:** the design names a 3D, interactive or motion signature but the captures show a static, placeholder or broken piece → high finding, Wow ≤ 5. +- Any transition with no answer to "what becomes the next thing?" (`signature.md`) → medium; more than one → high. +- Strict mode: any off-spec token, component or motion value (`M3E:` checklist) → high; a choice made where the spec allows it but not listed with its spec reference → medium. + +## Each critique states +1. **Wow** and **Craft**, each with a one-line justification against the anchors. +2. **The screenshot-worthy moment** in one sentence, or "none". +3. **Grounding** test result. +4. **Signature check:** the `signature.md` items that hold and those that fail. +5. **Weakest thing on screen.** +6. **Findings** high / medium / low, each naming the capture that shows it: high = broken state, unreadable text, jank or a pop (a spike in the frame list where nothing should jump, or a flat stretch where the page claims to move), a high slop-scan hit, a fake signature, off-spec in strict mode; medium = people notice; low = only a designer notices. +7. **Next verb(s)** from `verbs.md` (one or two), or `done`. + +## Cull (sketch round) +Sketches are cheap stills plus a storyboard; judge the idea, not the polish. +- Score each sketch 3-10 on **idea strength** (does the signature moment in the storyboard have a real "what becomes the next thing" chain; would it be worth building), and note grounding (name-swap test) and whether it obeys its seed. +- Drop: below 6, failed grounding, a storyboard with no real transition chain, an off-spec seed in strict mode, and the weaker of any two that share a world or motion idea. +- Keep 4-8 ranked (fewer only if fewer deserve it). Always keep the best ambitious interactive/3D sketch if it scored 6 or more. +- Format per sketch: `s<k> | score | keep/drop | one line why | for kept: the quality to protect`. + +Scores from earlier rounds are not shown to a new critic; each critic starts fresh. diff --git a/skills/design/references/seeds.md b/skills/design/references/seeds.md new file mode 100644 index 0000000..20b8f87 --- /dev/null +++ b/skills/design/references/seeds.md @@ -0,0 +1,30 @@ +# Seeds: making sketches diverge + +Divergence has to be forced. Asked for "variations", models converge on the category default. A seed is a deliberate constraint on three axes, chosen so no two sketches share more than one axis. +Ideas from Impeccable's concept roll (Apache-2.0) and Charles' unreasonable-craft (paraphrased); the signature rules are in `signature.md`. + +## The three axes (default mode) +- **Material / world:** what the page is made of, taken from the subject's world: an object, a place, a notation, a process, a print tradition, a medium. Not a style name like "brutalist" or "glassmorphism". +- **Motion idea:** the one thing that moves and why: a camera travelling through a scene, a line that draws the content's own sequence, a shape that becomes each next section, a pinned object that transforms, a live value that keeps updating, a live 3D subject whose form changes with the content, almost no motion (a still, typographic page). +- **Type move:** how type behaves: type as architecture (huge, the space you move through), a quiet text column beside a rich object, type set into the material, a dense ledger, one typeface at many sizes. + +## Making the seeds (count from the launch, default 10) +1. Read facts and taste. Write the page this category always ships, and its obvious opposite: both are banned as seeds. +2. Write one line per seed: `material | motion idea | type move | the content it puts first | the signature moment in one sentence`. +3. Spread: + - **Ambitious interactive/3D:** at least 1 seed is a live 3D or deeply interactive piece (a scroll-driven camera through a scene, a 3D subject that changes form with each section, a world you click through). If the taste brief asks for 3D, motion or interactivity, at least 2. For app UIs, "ambitious" means a signature interaction (a morphing control, a spatial transition between views), not a 3D scene. + - at least 1 seed with almost no motion, carried by type and composition; + - at least 1 seed built on the content's own sequence or process; + - no two seeds share a material family. +4. Each seed must be able to show the real facts; a seed that needs invented content is dropped. +5. Below the seeds, list the banned default and opposite from step 1. + +## Strict mode (m3e-strict) +The spec fixes tokens, components and motion, so seeds diverge on what the spec leaves open: +- **Layout archetype** for the window size class (list-detail, supporting pane, feed, single focus) where the spec allows several. +- **Expressive emphasis:** which one or two expressive features carry the design (shape morphing, emphasized type, a hero component such as a large button group or a wavy progress indicator, tonal colour from content) and where they sit. +- **Content first:** which content leads the first screen. +Every seed lists the spec choices it relies on (the `Room for choice:` items in `M3E:`). A seed that needs an off-spec value is dropped. + +## A sketch is +One self-contained HTML file with the first screen finished with care and real content, plus a storyboard file: 3 key frames of the signature motion ("what's on screen → what it becomes") and one paragraph on the idea. Quick, honest, real content. No interaction or animation code; a 3D seed shows its key pose as a still. Not a moodboard. diff --git a/skills/design/references/signature.md b/skills/design/references/signature.md new file mode 100644 index 0000000..9acfe07 --- /dev/null +++ b/skills/design/references/signature.md @@ -0,0 +1,35 @@ +# Signature: what makes a design worth a screenshot + +A page without a signature is a template with nice type. These rules describe what the memorable pages share; they don't prescribe a look. Read with `motion.md` (tools, timings, budgets). +Written for devline from studies of award-level scroll pieces and product reels; paraphrased. + +## The rules +1. **One continuous world, no cuts.** Nothing pops in. Every new state is something already on screen turning into the next thing, so the eye never has to find its place again. +2. **Matched transitions: "what becomes the next thing?"** The end of one motion is the start of the next. A shape, object or line is the bridge between sections: a pour becomes the next vessel, a wireframe block becomes the glow above a wordmark, a node becomes a card. Every transition needs a written answer; if there is none, redesign it. +3. **Two layers of motion.** The container moves (a scene opens, a camera travels, a layout reshapes) while the content inside keeps living at rest (a line rewrites itself, a value updates, a detail lights up). Small and calm, never wobble. +4. **One physical model.** One light source, consistent shadows, one easing family, weight in the motion. Because it obeys rules, it reads as real rather than as "animation". +5. **The subject's own process is the narrative.** The structure of the content is the structure of the motion: brewing for a coffee brand, dusk to dark for an observatory, a request travelling through services for a backend engineer. +6. **Type is part of the scene.** Headlines are big, short and layered between objects (an object overlaps the word it names). One idea per screen. +7. **Rhythm: hold, decisive move, hold.** Calm for a beat, a fast eased transition, calm again. +8. **Bookend.** The end resolves back to the opening state or shape, so it feels finished. +9. **Shape-led layout.** Content sits in masks and non-rectangular shapes; geometry carries over from one state to the next. +10. **Still the subject.** However ambitious, it must read as what it is (an engineer's portfolio, an observatory, a music app), not as a design studio's showreel. + +## Worked patterns (describe the quality, never copy a layout) +- **Live 3D subject on a natural scroll.** One 3D object stays on screen through the whole page and changes form to picture each section's content, and each form causes the next: a stream of tokens gathers into one block, the block splits into several, most of them move, they compile into a diagram, the diagram's lanes run in parallel, and everything closes into a ring that echoes the opening. Native scroll, no hijack; type in a serif display + clean sans beside it. +- **Type as architecture.** Giant words are the scenery. The camera flies through a letter's counter (the hole in an "O") into the room behind it, where the next section lives; each room ends in another word to fly through; the last flight lands on the opening word. One exponential dolly per flight, no snap, no parallax. +- **The object you leaf through.** A closed book on a lit desk opens in 3D; every spread is a section; pages curl and darken as they tilt from the light; while a spread rests, its content keeps living; at the end the book closes into the opening frame. +- **Morphing wireframe.** Coloured blocks labelled by role slide and reshape into the next layout and real content fills the exact shapes; the last shape becomes a graphic element of the final screen. + +## What counts as "real" 3D or interaction +- It runs: the captures show it moving and changing with scroll or input, at 60 fps (frame list with no spikes where nothing should jump). +- It carries content: the 3D or interactive piece pictures the section it sits in, not a spinning decoration beside it. +- It degrades: a designed static fallback (no WebGL) and a reduced-motion state that shows the key frames. +- A static image, a looping decorative blob, a canvas that only reacts to the cursor, or a 3D scene that doesn't change with the content is **not** a signature. + +## Craft checks for any signature +- Every transition: write "X becomes Y". Missing → redesign. +- One light/shadow model, one easing family, one rhythm. +- Every resting state has one small living detail. +- Reduced motion and no-JS: the clean static page, fully readable. +- Lightest tool first: CSS scroll-driven animations and View Transitions, then GSAP, then three.js (`motion.md` chooser). diff --git a/skills/design/references/verbs.md b/skills/design/references/verbs.md new file mode 100644 index 0000000..ba744ad --- /dev/null +++ b/skills/design/references/verbs.md @@ -0,0 +1,16 @@ +# Steering verbs: one named change per refine pass + +Adapted from Impeccable's commands (Apache-2.0) and Emil Kowalski's animation skills (MIT). A refine pass applies one or two verbs the critic chose, across the whole page, and nothing else. + +| Verb | Use when the critic says | What changes | +|---|---|---| +| `bolder` | Safe, forgettable, "looks like everything else" | Commit harder to the world: bigger scale contrast, one braver color or form decision, the Moment made larger and more central. Never add decoration to get there. | +| `quieter` | Busy, competing elements, too much motion | Remove effects and secondary motion, drop to one accent, more space, fewer type sizes. The Moment stays. | +| `distill` | Cluttered, generic sections, card soup | Cut sections/elements to the essential, merge, replace containers with spacing and alignment. Answer "what breaks if this is gone?" for each element. | +| `typeset` | Type looks default or wrong for the character | Change faces, scale, measure, leading, tracking; theme selection/numerals; balance headings. | +| `animate` | Static where motion would explain, or motion that pops/steps | Build the motion story: bridges between beats, scroll-scrubbed continuity, pinned scenes that keep moving, two layers, bookends. Follow `motion.md`. | +| `polish` | Good idea, visible defects | Fix contrast, alignment, spacing rhythm, states, focus, hit areas, phone layout, reduced-motion state, console errors. | +| `harden` | Breaks in some state | Empty/error/no-JS/no-WebGL/reduced-motion paths, long text, 1000-1100 px widths. | +| `reground` | Swapping in another subject's name would still fit | Pull more of the subject's real content and world into the structure itself; replace generic sections. | + +Rules: one verb, maybe two, per pass. Keep what the critic called the best thing. After the pass, capture again; the critic decides the next verb. diff --git a/skills/design/references/web/accessibility.md b/skills/design/references/web/accessibility.md new file mode 100644 index 0000000..b9f779b --- /dev/null +++ b/skills/design/references/web/accessibility.md @@ -0,0 +1,586 @@ +<!-- Source: https://github.com/GoogleChrome/modern-web-guidance v1.0.0 (4dd9683), skills/modern-web-guidance/guides/accessibility/accessibility.md. Apache-2.0 (see ../LICENSE-APACHE). Copied unchanged. --> +# Accessibility Coding Guidelines + +This guide provides actionable DOs and DON'Ts for AI coding agents to ensure web applications are accessible to all users, including those using assistive technologies. + +Keep these principles in mind throughout: + +- **Accessibility is the minimum, not the ceiling.** Conformance to standards is the floor; aim for genuine usability. +- **Patterns are use-case specific.** No checklist replaces real testing — including testing with disabled users — to confirm a given implementation is actually accessible in context. + +Contents: + +- [1. Content Navigability and Structure](#1-content-navigability-and-structure) + - [Landmarks](#landmarks) + - [Headings](#headings) + - [Lists](#lists) + - [Tables](#tables) + - [Skip links](#skip-links) + - [Code example: good use of landmarks, headings, lists, tables, and a skip link](#code-example-good-use-of-landmarks-headings-lists-tables-and-a-skip-link) +- [2. Semantic HTML and ARIA](#2-semantic-html-and-aria) + - [Prefer native HTML](#prefer-native-html) + - [ARIA roles and states](#aria-roles-and-states) +- [3. Accessible Names and Descriptions](#3-accessible-names-and-descriptions) + - [Naming mechanisms](#naming-mechanisms) + - [Choosing the name](#choosing-the-name) + - [Descriptions](#descriptions) + - [Code Example: Visually Hidden Utility](#code-example-visually-hidden-utility) +- [4. Document Metadata and Language](#4-document-metadata-and-language) + - [Language](#language) + - [Titles](#titles) + - [Iframes](#iframes) + - [Code Example: using the `<title>` and `<iframe>` elements](#code-example-using-the-title-and-iframe-elements) +- [5. Keyboard and Focus Management](#5-keyboard-and-focus-management) + - [Tab order and focusability](#tab-order-and-focusability) + - [Keyboard handlers](#keyboard-handlers) + - [Focus indicators](#focus-indicators) + - [Target sizes](#target-sizes) +- [6. Alternate Text and Media](#6-alternate-text-and-media) + - [Images](#images) + - [Inline SVGs](#inline-svgs) + - [Complex images and charts](#complex-images-and-charts) + - [Audio and video](#audio-and-video) + - [CSS generated content](#css-generated-content) + - [Content Visibility Decision Matrix](#content-visibility-decision-matrix) +- [7. Forms and Input Controls](#7-forms-and-input-controls) + - [Labels and hints](#labels-and-hints) + - [Input assistance and validation](#input-assistance-and-validation) +- [8. Live Regions](#8-live-regions) + - [Live Region Urgency Table](#live-region-urgency-table) + - [When to announce](#when-to-announce-live-regions) + - [Managing announcements](#managing-announcements) +- [9. Color](#9-color) +- [10. Typography](#10-typography) +- [11. Motion and Preferences](#11-motion-and-preferences) +- [12. Modals and Native Dialogs](#12-modals-and-native-dialogs) + - [Native `<dialog>`](#native-dialog) + - [Custom overlays](#custom-overlays) +- [13. Testing Validations](#13-testing-validations) + - [Automated checks](#automated-checks) + - [Manual testing](#manual-testing) + +## 1. Content Navigability and Structure + +### Landmarks + +- **Place all content within landmarks:** Wrap each relevant part of the page in `<header>`, `<nav>`, `<main>`, `<aside>`, and `<footer>` elements so assistive-tech users can jump between regions. (1.3.6 Identify Purpose (Level AAA)) +- **Use the correct landmark:** Use the `<header>` element as a container for introductory content, the `<nav>` element as a container for site-wide or in-page navigation links, the `<main>` element as a container for the main content of the page, the `<aside>` element as a container for content that is tangentially related to the main content, and the `<footer>` element as a container for information about the related content, such as the author, copyright information, and links to related documents. (1.3.1 Info and Relationships (Level A)) +- **Use one `<main>` landmark per page:** Avoid using multiple `<main>` elements on a single page. (1.3.1 Info and Relationships (Level A)) +- **Provide distinguishable accessible names for navigation regions:** If a page contains multiple `<nav>` elements, apply the `aria-label` attribute to each element and set its value to a distinguishable accessible name for the region. For example: `<nav aria-label="Primary">`, `<nav aria-label="Secondary">`, and so on. (Best practice) +- **Don't overuse landmarks:** Too many landmarks dilute their value. In particular, avoid labeling a `<section>` (which turns it into a `region` landmark) — `region` should be a last resort when no other landmark fits. (Best practice) + +### Headings + +- **Structure main content with headings:** Use `<h1>`–`<h6>` elements sequentially so screen reader users get a navigable outline. (1.3.1 Info and Relationships (Level A)) +- **Mandatory - Don't use "fake" headings:** Never use `<div>` or `<span>` elements to look like headings without standard `<h1>`–`<h6>` elements. (1.3.1 Info and Relationships (Level A)) +- **Avoid nesting headings incorrectly:** Make sure that, if a sub-heading is visually less important than its parent heading, its heading level is lower in the heading hierarchy. (1.3.1 Info and Relationships (Level A)) +- **Use one `<h1>` element per page:** Use the `<h1>` element for the page's main heading. Having more than one `<h1>` element on a page makes it difficult for screen reader users to identify the actual main heading. (Best Practice) + - **Caveat:** If a page includes a modal dialog that is marked up using the `<dialog>` element, `role="dialog"`, or `role="alertdialog"`, it is fine to mark up its main heading using the `<h1>` element because the dialog is a new window that is separate from the page. +- **Avoid "skipped" heading levels:** Avoid jumping directly from (for example) `<h1>` → `<h4>` to avoid breaking the logical hierarchy. (Best Practice) +- **Avoid placing headings inside the `<summary>` element:** Some browsers still expose this element as a button, which removes all roles from its children including headings. If a heading must act as a disclosure trigger, use an accordion or a disclosure implemented with ARIA where the heading element wraps the button, rather than use the `<details>` and `<summary>` elements. (Best Practice) + +### Lists + +- **Use lists for repeated, contiguous content:** `<ul>`/`<ol>` give assistive tech a count of listitems up front and let users skip the entire list. (1.3.1 Info and Relationships (Level A)) +- **Use the correct list element:** Use the `<ul>` element for unordered lists where the order of the items is **not** important (such as a list of related products), and use the `<ol>` element for ordered lists where the order of the content **is** important (such as a list of instructions). (1.3.1 Info and Relationships (Level A)) +- **Don't use lists for non-list content:** Do not use list markup to mark up separate paragraphs of text, as screen readers will announce list information when they encounter lists, therefore leading to a screen reader hearing potentially confusing and redundant information about the related content. (1.3.1 Info and Relationships (Level A)) +- **Don't use lists for checkboxes and radio buttons:** When marked up correctly, screen readers will already announce the number of checkboxes or radio buttons, as well as the number of the currently focused checkbox / radio button in the set, even though there is no list markup. Additional list markup will lead to duplication. (1.3.1 Info and Relationships (Level A)) + +### Tables + +- **Do use the correct table elements:** Use the `<table>` element to identify the table, the `<caption>` element to provide a title and accessible name for the description, the `<tr>` element to identify individual rows in the table, and the `<th>` and `<td>` elements to identify header and data cells respectively. (1.3.1 Info and Relationships (Level A)) +- **Do use the `scope` attribute on `<th>` elements:** The `scope` attribute indicates whether the `<th>` element represents a row header (`<th scope="row">`) or a column header (`<th scope="col">`). (1.3.1 Info and Relationships (Level A)) +- **Mandatory - Don't use tables for layout:** Screen readers will announce redundant information about the layout, which may be confusing for screen reader users, while the use of tabular markup has an impact on the reading and keyboard focus order of content. Use CSS Grid/Flexbox for visual layouts instead. (1.3.1 Info and Relationships (Level A)) +- **Avoid overly-complex tables:** Spanned rows, spanned columns, nested tables, and expandable / collapsible rows can make sense visually and meet the related WCAG success criterion, but the overall structure can be disorienting and difficult to navigate for screen reader users. In such cases, break tables up into smaller tables that are easier and more efficient to navigate. (Best Practice) + +### Skip links + +- **Provide skip links** prior to repeated content like site headers with navigation or long/infinite lists, so that keyboard users can easily bypass them. (2.4.1 Bypass Blocks (Level A)) + - **Caveat:** Sometimes screen magnifiers do not follow the focus when a skip link’s target is not normally focusable. + The recommended workaround is to make the target programmatically focusable, but not a part of the tab order, using `tabindex="-1"`. + If the target contains focusable elements, this creates another usability issue as clicking within the target will always set the **sequential focus navigation start point** to the target rather than at a point between focusable elements. + A solution that satisfies both user expectations is to make the first meaningful element within the intended target the actual target of the skip link with `tabindex="-1"`, for example a heading (`<h1 id="content" tabindex="-1">`). + Beware that any content prior to such an element will be skipped, including other relevant content within the targeted section, and this creates usability gaps for other assistive tech users. +- **Avoid using skip links where they are not needed:** A set of pages whose only common element is a single link to the Home page does not need a skip link. (Best Practice) +- **Avoid overusing skip links:** A single skip link, or two skip links to cover the primary and secondary sets of common navigation links, is usually sufficient on a single page. Multiple unnecessary skip links add to the number of <kbd>Tab</kbd> stops to a page, which causes frustration for people who use the keyboard alone for navigation. (Best Practice) + +```html +<!-- Good: Skip to main content --> +<a href="#content" class="skip-link">Skip to main content</a> +<main id="content">...</main> +``` + +### Code Example: good use of landmarks, headings, lists, tables, and a skip link + +```html +<!-- Good: Semantic landmarks, heading hierarchy, skip link --> +<header> + <a href="#platform-dashboard" class="skip-link visually-hidden">Skip to content</a> + <nav aria-label="Primary"> + <ul> + <li><a href="/">Home</a></li> + </ul> + </nav> +</header> +<main> + <h1 id="platform-dashboard" tabindex="-1">Platform Dashboard</h1> + <section> + <h2>User Statistics</h2> + <table> + <caption>Monthly active users</caption> + <thead> + <tr> + <th scope="col">Month</th> + <th scope="col">Users</th> + </tr> + </thead> + <tbody> + <tr> + <td>January</td> + <td>12,000</td> + </tr> + </tbody> + </table> + <h3>Notes</h3> + <ul> + <li>Results do not include users without active subscriptions</li> + <li>Results are accurate as of 31 December 2025</li> + </ul> + </section> +</main> +``` + +## 2. Semantic HTML and ARIA + +### Prefer native HTML + +- **Prefer HTML elements and attributes to ARIA:** Avoid `<div role="button">` or `<a role="button">` and use `<button>` instead. Native HTML elements and attributes already have the correct role and behavior, including keyboard support, built-in by default. `<button>` already implies `role="button"`, `required` already implies `aria-required`, and no additional JavaScript is required to ensure the correct role and behavior is supported. (Best Practice) + - **Caveat:** ARIA is required when the related feature is not available in HTML, for example there are no HTML elements explicitly intended for building a tabbed navigation widget, but ARIA includes appropriate role and state properties for this purpose. +- **Don't add redundant ARIA roles or properties:** Avoid `<ul role="list">`, `<nav role="navigation">`, and `<input required aria-required="true">`. (Best Practice) + - **Caveat:** Safari removes list semantics from `<ul>`/`<ol>` outside `<nav>` when `list-style: none` or `display: flex`/`grid` is applied. In that case `role="list"` is required to restore them. +- **Don't apply interactive ARIA roles to structural HTML elements:** Use `<li><span role="button">Button in a list</span></li>`, not `<li role="button">Button in a list</li>`, to avoid breaking the container list semantics. (4.1.2 Name, Role, Value (Level A)) + - **Caveat:** It is acceptable to apply ARIA roles to structural HTML elements that have similar semantics, for example a tree view: `<ul role="tree"><li role="treeitem">…</li>…</ul>`. + +### ARIA roles and states + +- **Match ARIA implementations to actual behavior:** When applying `role="tab"` to an element, it must then behave like a tab — including keyboard interactions. Many ARIA patterns can't be implemented in CSS alone and need JavaScript. (4.1.2 Name, Role, Value (Level A)) +- **Manage toggle states:** Utilize `aria-expanded` and `aria-pressed` to communicate toggle states for custom controls. (4.1.2 Name, Role, Value (Level A)) +- **Be deliberate about `disabled` vs `aria-disabled`:** `disabled` removes the element from the focus order entirely (and `tabindex="0"` won't bring it back), which is often wrong for toolbar buttons or links. `aria-disabled="true"` keeps the element focusable so users can land on it and learn it's disabled, but because it only communicates state to assistive technologies, you must also prevent activation (such as pointer clicks and keyboard triggers) in JavaScript. (4.1.2 Name, Role, Value (Level A)) +- **Mandatory - Don't hide interactive elements from screen readers:** Do not apply `aria-hidden="true"` to interactive elements that receive focus, or to their parent elements. (4.1.2 Name, Role, Value (Level A)) +- **Mandatory - Don't suppress the roles of interactive elements:** Applying `role="presentation"` or `role="none"` to an interactive element strips its semantics. The element will still be exposed to assistive technologies and announced by screen readers, but its role and any state information will not be, which results in confusion and potentially unexpected behavior. (4.1.2 Name, Role, Value (Level A)) +- **Don't assume custom elements have no ARIA:** Custom elements can attach ARIA via `ElementInternals`, which some automated test tools can't see — so the absence of `role`/`aria-*` attributes in markup doesn't prove the element has no semantics. Verify with the browser's accessibility-tree inspector. (Best Practice) + +## 3. Accessible Names and Descriptions + +Every interactive element and some landmarks need an accessible name, and many benefit from an accessible description. Names are short and identify the element; descriptions add context. + +### Naming mechanisms + +- **Prefer native naming mechanisms:** `<label>` for form controls, `<caption>` for `<table>`, `<legend>` for `<fieldset>`, `<figcaption>` for `<figure>`. (Best Practice) +- **Explicitly associate `<label>` with its control via `for`/`id`:** As well as ensuring the control is appropriately labeled by the contents of the `<label>` element, this results in a larger target area for people to activate the label _or_ its related control to move focus to the control, which isn't globally supported with other forms of labeling (such as using the `aria-labelledby` attribute). Additionally, some assistive technologies, particularly voice recognition software, require the `for`/`id` relationship to be explicitly set, even if an equivalent accessibility-supported approach (such as nesting an `<input>` inside a `<label>`) is taken. (4.1.2 Name, Role, Value (Level A)) +- **Prefer `aria-labelledby` over `aria-label` when a visible label exists:** This avoids duplication, improves maintainability, and translates better. (Best Practice) +- **Don't use `title` as a naming mechanism:** The value of this attribute is only displayed on mouse hover, and cannot be displayed or otherwise accessed using the keyboard in any browser. (Best Practice) + - **Caveat:** `<iframe>` is an exception, as the `title` attribute is the standard way of providing an accessible name for this element. +- **Don't use `placeholder` as a naming mechanism:** While the value of this attribute is initially displayed inside an `<input>` or `<textarea>`, it disappears as soon as the user enters text into the field, meaning that there is no longer a visual cue as to what the field represents. The contrast between `placeholder` text and its background in most browsers is very low, and therefore is difficult for people to perceive. (3.3.2 Labels or Instructions (Level A)) +- **Don't put `aria-label`/`aria-labelledby` on elements that shouldn't be named:** Examples include plain `<div>`, `<span>`, and other custom elements without a role. These attributes are only intended for providing accessible names for elements that have explicit or implicit widget (for example, button, link, and tab), landmark, image, or iframe roles. (1.3.1 Info and Relationships (Level A)) + - **Caveat:** Custom elements may have an implicit role set via `ElementInternals`, so the absence of a `role` attribute isn't conclusive. + +### Choosing the name + +- **Avoid inconsistent link text:** If multiple hyperlinks direct users to the same target page, make sure each link has the same accessible name, which should typically be the same as its visible link text. For example, if the target page for a link is `profile.html`, make sure that all links have an accessible name of "My Profile" **or** "Profile"; do not use "My Profile" in one instance, and "Profile" in the other. (Best Practice) +- **Disambiguate controls that look visually identical but which perform different actions by their accessible name:** For example, a page may include multiple "Edit" buttons, each of which triggers functionality to perform a different action, such as edit the user's name, edit the user's password, and edit the user's address. While it may be visually obvious from the surrounding content what the purpose of these buttons might be, screen reader users may only hear "Edit, button". Techniques to resolve this include the following: (4.1.2 Name, Role, Value (Level A)) + - **Use visually hidden text:** The text is included in the DOM but is visually hidden using CSS. For example `<button>Edit <span class="visually-hidden">first name</span></button>`. Refer to the [code example: visually hidden utility](#code-example-visually-hidden-utility) for the full CSS. + - **Apply the `aria-label` attribute to the control:** The value of this attribute should then include the visible text as well as important contextual information, for example `<button aria-label="Edit name">Edit</button>`, `<button aria-label="Edit address">Edit</button>`, and so on. + - **Use the `aria-labelledby` or `aria-describedby` attribute to associate the control with the content it relates to:** Chaining IDs in `aria-labelledby` appends the related text to the control's accessible name (for example, `<p id="firstName">First name</p> <button id="editFirstName" aria-labelledby="editFirstName firstName">Edit</button>`), whereas `aria-describedby` provides the context as an accessible description (`<p id="firstName">First name</p> <button aria-describedby="firstName">Edit</button>`). +- **Do include a control's visible text in its accessible name:** Any visible text used to label a control must be included exactly as written in the control's accessible name. The accessible name can include additional information before or after the visible text, but the visible text itself must not differ. For example, the accessible name for a link containing the link phrase "Read more" can be "Read more about [subject]", because the visible text is included without modification. However, the accessible name cannot be "Read some more about [subject]", because the term "some" appears between the words "Read" and "more", which is not reflected in the visible text. (2.5.3 Label in Name (Level A)) +- **Don't reuse an accessible name across controls with different effects in the same view:** Make sure that each accessible name is disambiguated. (4.1.2 Name, Role, Value (Level A)) + - **Caveat:** Having two separate buttons with the accessible name of "Close" in two separate dialog boxes is fine, because only one dialog box is reachable at a time; however, multiple "Edit" buttons for different effects in the same dialog box is not. +- **Don't reuse an accessible name across hyperlinks that point to different `href` targets:** For example, avoid `<a href="annualreport2025.html">Annual Report</a>` and `<a href="annualreport2026.html">Annual Report</a>`. Use `<a href="annualreport2025.html">Annual Report 2025</a>` and `<a href="annualreport2026.html">Annual Report 2026</a>` (or an equivalent technique for disambiguating controls) instead. +- **Don't pack descriptions, error messages, or instructions into the label:** Verbose labels confuse and frustrate people who use screen readers. Instead, use the `aria-describedby` attribute to programmatically associate any additional content with the field. For example: `<label for="yourComments">Your comments</label><p id="yourCommentsWarning">Please do not include any personal information in this field.</p><textarea id="yourComments" aria-describedby="yourCommentsWarning"></textarea>`. Screen readers will then announce the label first, followed by the control type, and only then announce additional information that a user can skip if they are already aware of it. (Best Practice) +- **Don't repeat state information already exposed by ARIA inside the label:** Examples include information exposed via the `aria-expanded`, `aria-checked`, `aria-selected`, `aria-pressed`, and similar attributes. This creates duplication, redundancy, and ambiguity. (Best Practice) +- **Don't include the role name in the label:** This will lead to duplication. For example, `<nav aria-label="Primary navigation">` will be read by screen readers as "Primary navigation, navigation". (Best Practice) + +### Descriptions + +- **Identify instructions, error messages, and any other important information explicitly related to a control as a description:** Examples of descriptions include: (1.3.1 Info and Relationships (Level A)) + - A list of password requirements when creating an account + - An error message related to a field in a previously submitted form + - Additional instructions, such as "You must agree to the terms and conditions before you can submit the form" +- **Make sure the description is available to assistive technologies when the related element receives focus:** Take one of the following approaches (1.3.1 Info and Relationships (Level A)): + - If the description is already visible on the page, programmatically associate it with the element using the `aria-describedby` attribute. + - If the description is not visible on the page and is explicitly for screen reader users (in other words, when providing a visible description is not appropriate or useful), apply the `aria-description` attribute to the element and use it to provide an appropriate description. +- **Avoid including a description for every element:** if the primary label already provides sufficient information (such as "First name"), any additional description is likely to be redundant. (Best Practice) + - **Caveat:** Inline error messages associated with controls, such as error messages below / above text fields, as well as secondary labels that should be announced when the element receives focus, are exceptions. +- **Avoid including information in the description that is already provided by attributes applied to the element:** For example, including "This is a required field" as a description for an `<input>` element that already includes the `required` attribute will lead to duplicate announcements. (Best Practice) + - **Caveat:** `aria-invalid="true"` is an exception; many screen readers announce "invalid" when they reach an `<input>` that includes this attribute set to `true`, which indicates that the field is in error. However, it does not indicate what the error is. In such cases, a description (the actual human readable error message) is required. This attribute should only be applied and set to true when the error message is present. +- **Avoid including interactive elements in an `aria-describedby` target** unless the content of the element reads sensibly as a description on its own. For example: (Best Practice) + - This is acceptable, as the entire text string makes sense when announced: `<p id="description">I understand the <a href="tandc.html">terms and conditions</a>.</p>` + - This is not appropriate, as the description will be announced as "Please don't include personal information in this field. Learn more.", where "Learn more" will be announced out of its intended context: `<p id="description">Please don't include personal information in this field. <a href="…">Learn more</a></p>`. Instead, only include the plain text in the referenced description: `<p><span id="description">Please don't include personal information in this field.</span> <a href="…">Learn more</a></p>`. + +### Code Example: Visually Hidden Utility + +A `.visually-hidden` utility provides text for screen readers without rendering it visually. It's commonly used for skip links, additional context on icon-only buttons, and supplementary labels. + +```css +/* Hides content visually but keeps it in the accessibility tree. + :focus-within / :active opt elements out — useful for skip links and + any focusable content wrapped in this class. */ +.visually-hidden:where(:not(:focus-within, :active)) { + position: absolute !important; + clip-path: inset(50%) !important; + overflow: hidden !important; + width: 1px !important; + height: 1px !important; + margin: -1px !important; + padding: 0 !important; + border: 0 !important; + white-space: nowrap !important; +} +``` + +When the hidden content is focusable (skip links, focus-receiving wrappers), the `:focus-within`/`:active` exception lets it become visible. Style the visible state per situation, e.g. a skip link to the main content typically wants fixed positioning at the top-left of the viewport so the rest of the page doesn't shift. + +## 4. Document Metadata and Language + +### Language + +- **Do declare the page's human language:** Always apply the `lang` attribute to the page's `<html>` element, and always set it to the primary human language of the page's content. For example, `<html lang="en">`. (3.1.1 Language of Page (Level A)) +- **Do declare changes in the page's human language:** If there is a language change on the page, apply the `lang` attribute to the parent/container element for the affected content, and set the value of this attribute to the shortcode for the language of the affected content. For example: `<p>In Germany, you may be greeted by someone saying <span lang="de">Guten Morgen</span>.</p>`. (3.1.2 Language of Parts (Level AA)) +- **Don't set the value of the `lang` attribute to a value that doesn't match the human language of the content:** This causes screen readers and other text-to-speech software to announce the content in a non-understandable manner. (3.1.1 Language of Page (Level A), 3.1.2 Language of Parts (Level AA)) + +### Titles + +- **Do include the `<title>` element in the `<head>` section for all pages:** This includes pages embedded into a document using an `<iframe>`. (2.4.2 Page Titled (Level A)) +- **Provide unique page titles:** Every page should have its own title that unambiguously reflects the page's purpose or content. (2.4.2 Page Titled (Level A)) +- **Front-load the page's `<title>` with unique content:** For example, `<title>Page Topic | Site Name`. (Best Practice) +- **Update single-page application (SPA) titles during page transitions:** For example, if the page title is `Contact Us` when a contact form is displayed, update the title to `Thank you for contacting us!` when the form is successfully submitted. (2.4.2 Page Titled (Level A)) +- **Don't include an empty `` element in the `<head>` section of a page:** No matter how short or inconsequential a page appears, do not use `<title>`. Page titles appear in the browser tab, so pages are distinguishable when users have multiple tabs open, and are typically announced by screen readers when the page is opened. (2.4.2 Page Titled (Level A)) +- **Avoid using the same title for multiple pages, or using ambiguous page titles:** In such cases, pages are indistinguishable without reviewing the actual page content itself. (2.4.2 Page Titled (Level A)) + +### Iframes + +- **Do provide a descriptive `title` for ` + + +``` + +## 5. Keyboard and Focus Management + +### Tab order and focusability + +- **Provide a logical tab order:** Make sure that the order in which elements receive focus follows an appropriate sequence. (2.4.3 Focus Order (Level A)) + - **Caveat:** In left-to-right reading languages, the tab order is logical when focus moves from top-to-bottom and left-to-right. However, in right-to-left reading languages, the tab order is logical when focus moves from top-to-bottom and right-to-left. +- **Use `tabindex` only when necessary:** Apply `tabindex="0"` to elements requiring focus where an appropriate interactive role has been applied but the element isn't focusable by default; for example, `Print` (2.4.3 Focus Order (Level A)) +- **Manage focus correctly to and from updated content:** For example, if a dialog box appears on the page, make sure that focus immediately moves to the dialog box, is restricted to the contents of the dialog box, and (when dismissed) returns to the element that originally triggered the dialog box. (2.4.3 Focus Order (Level A)) +- **Don't apply `tabindex="0"` to interactive elements that are already focusable by default:** Native elements like the `