diff --git a/README.md b/README.md index 7024076b..70945702 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ ### A community-maintained marketplace of skills, agents, and rules for Claude Code.

- 6 plugins · 37 skills · 3 agents · MIT + 6 plugins · 38 skills · 3 agents · MIT

@@ -137,7 +137,7 @@ that tool's model via the **LLM tier reference** below. ### 🧭 [aidd-context](plugins/aidd-context/README.md) -`12 skills` · stable +`13 skills` · stable Project init, architecture, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks), diagrams, learning, discovery. diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 50076a6b..893b1b6c 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -21,6 +21,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`skills/09-mermaid`](#skills09-mermaid) - [`skills/10-learn`](#skills10-learn) - [`skills/11-discovery`](#skills11-discovery) + - [`skills/12-design-system`](#skills12-design-system) --- @@ -195,3 +196,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [ai-mapping.md](skills/11-discovery/references/ai-mapping.md) | - | | `-` | [SKILL.md](skills/11-discovery/SKILL.md) | `Enumerate installed surfaces of the AI tool (skills, agents, commands, plugins, MCP servers, rules, hooks, memory files) and recommend the best match for the user's stated intent. Use proactively whenever the user asks the model to list, show, enumerate, find, or pick among any of these surfaces - including imperative phrasings ("list hooks", "show me the rules", "enumerate skills", "find a memory file", "which agent reviews code"), question phrasings ("what's available?", "what hooks do we have?", "which rule applies here?", "what memory files do we have?"), and indirect phrasings ("what can I use for X?", "do we have something that does Y?"). Always pick this skill over scanning the filesystem with grep, find, ls, or reading action files directly when the user is enumerating a surface. Do NOT use for picking a specific item inside one plugin (the plugin's own onboard handles that), creating a new surface, or executing a recommended item (this skill only points; the user invokes).` | +#### `skills/12-design-system` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-create-design-system.md](skills/12-design-system/actions/01-create-design-system.md) | - | +| `actions` | [02-redesign-page.md](skills/12-design-system/actions/02-redesign-page.md) | - | +| `-` | [README.md](skills/12-design-system/README.md) | - | +| `-` | [SKILL.md](skills/12-design-system/SKILL.md) | `Initialize a project's design system through a guided, ordered playbook that routes each step to the right Impeccable command - register and color strategy, palette with accessibility validation, typography, spacing, elevation, motion, components, and the canonical DESIGN.md.` | + diff --git a/plugins/aidd-context/README.md b/plugins/aidd-context/README.md index 6b2f0a17..56284f8e 100644 --- a/plugins/aidd-context/README.md +++ b/plugins/aidd-context/README.md @@ -8,7 +8,7 @@ Knowledge production plugin for the AI-Driven Development framework. First time? Install with `/plugin install aidd-context@aidd-framework`, then run `aidd-context:00-onboard`. -Covers project bootstrap, project initialisation, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks), Mermaid diagrams, learning, discovery, and a state-aware onboarding loop. +Covers project bootstrap, project initialisation, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks), Mermaid diagrams, learning, discovery, design-system onboarding, and a state-aware onboarding loop. ## Skills @@ -21,6 +21,7 @@ Covers project bootstrap, project initialisation, generation of Claude Code cont | [1.4] | [mermaid](skills/09-mermaid/README.md) | Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow. | | [1.5] | [learn](skills/10-learn/README.md) | Capture and store learnings from recently implemented features into memory bank, decisions, or coding rules. | | [1.6] | [discovery](skills/11-discovery/README.md) | Help users discover installed skills and find the right one for their use case. | +| [1.7] | [design-system](skills/12-design-system/README.md) | Guided playbook to author a quality design system by wrapping the Impeccable skill; routes each step to the right Impeccable command. Produces no files of its own - Impeccable's DESIGN.md stays canonical. | ## Onboarding diff --git a/plugins/aidd-context/skills/12-design-system/README.md b/plugins/aidd-context/skills/12-design-system/README.md new file mode 100644 index 00000000..a74807f5 --- /dev/null +++ b/plugins/aidd-context/skills/12-design-system/README.md @@ -0,0 +1,22 @@ +# 07 - Design System + +Guided onboarding for authoring a **quality design system**, wrapping the [Impeccable](https://impeccable.style) skill. Impeccable does the work (palette, typography, tokens, `DESIGN.md`); this skill adds the ordered playbook so no essential step is skipped. It writes **no design files of its own** - Impeccable's `DESIGN.md` stays canonical. + +## Usage + +``` +/aidd-context:12-design-system +``` + +Manual only. Two actions, both Impeccable runbooks with per-step checkboxes: + +- `01-create-design-system` - setup: `init` -> `document` -> `extract` -> refine -> `audit`/`critique`. +- `02-redesign-page` - improve an existing page. The AI invokes every Impeccable command itself; the user only answers questions and validates: `critique` (baseline score) -> ask what hurts -> axis commands (`layout`/`typeset`/`colorize`/`bolder`/`quieter`/`distill`/`animate`) -> show & validate -> `polish`/`audit`/re-`critique`, looping until no P0/P1 and the score beats the baseline. New patterns fold back via `extract`. + +## Requires + +The **Impeccable** skill (the playbook checks and guides install if missing). + +## Not for + +Authoring **new** page or component code - that is an implementation concern (Execution layer), where the implementer delegates the visual to Impeccable against this `DESIGN.md`. This skill founds the system and routes redesigns; Impeccable does the work and `DESIGN.md` stays canonical. diff --git a/plugins/aidd-context/skills/12-design-system/SKILL.md b/plugins/aidd-context/skills/12-design-system/SKILL.md new file mode 100644 index 00000000..3adc4d38 --- /dev/null +++ b/plugins/aidd-context/skills/12-design-system/SKILL.md @@ -0,0 +1,29 @@ +--- +name: 12-design-system +description: Initialize a project's design system through a guided, ordered playbook that routes each step to the right Impeccable command - register and color strategy, palette with accessibility validation, typography, spacing, elevation, motion, components, and the canonical DESIGN.md. +disable-model-invocation: true +--- + +# Skill: design-system + +Guided onboarding for authoring a quality design system. It does NOT generate the system - the [Impeccable](https://impeccable.style) skill already does (palette, typography, tokens, `DESIGN.md`). It adds the missing piece: an ordered playbook that routes each step to the right Impeccable command. Impeccable executes; `DESIGN.md` stays the single source of truth. + +## Transversal rules + +- **One source of truth**: Impeccable's root `DESIGN.md` (+ `.impeccable/design.json`). Never write a competing design file or a copy. Point, never copy. +- **Impeccable is a declared external dependency** - naming its commands is allowed; if absent, the playbook guides install. +- Per-step criteria are inline checkboxes in the action (walked as an AI-driven todo). No assets - the skill keeps no derived copy of `DESIGN.md`. +- English-only. + +## Available actions + +| # | Action | Role | Input | +| --- | ---------------------- | ---------------------------------------------------------- | ------------------ | +| 01 | `create-design-system` | Walk the playbook to a quality design system via Impeccable | project (optional) | +| 02 | `redesign-page` | Critique → fix weak axes → loop until the score holds | page (required) | + +## Default flow + +`01` founds the system (run once); `02` redesigns an existing page against it (run anytime, requires `DESIGN.md`). Both confirm Impeccable is available, then drive its commands. + +Authoring **new** page code is not this skill's concern (Knowledge layer) - that happens at implementation time, where the implementer delegates the presentational layer to Impeccable against this `DESIGN.md`. Redesigning an **existing** page's visual (action 02) is routing, not authoring: Impeccable executes, this skill orders the loop. diff --git a/plugins/aidd-context/skills/12-design-system/actions/01-create-design-system.md b/plugins/aidd-context/skills/12-design-system/actions/01-create-design-system.md new file mode 100644 index 00000000..6ab8c585 --- /dev/null +++ b/plugins/aidd-context/skills/12-design-system/actions/01-create-design-system.md @@ -0,0 +1,80 @@ +# 01 - Create design system + +A setup runbook: run Impeccable's commands in sequence, each setting up part of the design system. Output is Impeccable's canonical `DESIGN.md` (+ `PRODUCT.md` + `.impeccable/design.json`); this action only adds the ordering, the routing, and the per-step checks. Walk it as a todo: tick each checkbox once the command has produced it. + +## Inputs + +- `project` (optional, default: CWD) - project root to set the design system up in. +- `brand_intent` (optional) - a brand/product phrase if the user already has one; otherwise Impeccable's interview gathers it. + +## Outputs + +Impeccable-owned, at the project root (this action drives the commands, it doesn't write them): + +``` +PRODUCT.md # strategy: register, users, brand, anti-references +DESIGN.md # the single source of truth: tokens + 6 Stitch sections +.impeccable/design.json # sidecar: ramps, shadows, motion, components +``` + +## Process + +Run the commands in order. **Each step IS an Impeccable command**; tick its checkboxes once they hold. + +### Step 0 - Ensure the engine + +- [ ] `/impeccable` responds (installed). If absent, guide install (), then stop. Never emulate it. + +### Step 1 - `/impeccable init` + +Strategic foundation every later command reads. `init` defers all visual choices to `document` - it does not touch colors, fonts, or radii. + +- [ ] Register chosen: brand (design IS the product) vs product (design SERVES it) +- [ ] `PRODUCT.md` written: users, brand personality, anti-references, principles + +### Step 2 - `/impeccable document` + +The visual system, written to the canonical `DESIGN.md` + `.impeccable/design.json` sidecar (scan mode if code exists, seed mode if not). + +- [ ] Color strategy (Restrained / Committed / Full / Drenched) + one concrete mood sentence (not "modern/clean") +- [ ] Brand seed as OKLCH anchor (`palette.mjs` runs at Impeccable setup for new projects) +- [ ] Colors: semantic roles (primary/secondary/tertiary/neutral), OKLCH, descriptive slugs +- [ ] 8-step tonal ramp per major color (sidecar) +- [ ] Typography: pairing on a contrast axis, <=3 families +- [ ] Type scale + hierarchy (display/headline/title/body/label), step ratio >=1.25 +- [ ] Readability: line 65-75ch, clamp <=6rem, letter-spacing >=-0.04em, no all-caps body +- [ ] Spacing + radius token scales +- [ ] Elevation strategy stated (flat / tonal / shadows) +- [ ] Motion tokens + `prefers-reduced-motion` alternative +- [ ] Components documented with all states (default/hover/focus/active/disabled/loading/error) +- [ ] `DESIGN.md`: the six Stitch sections in order + token frontmatter +- [ ] Do's & Don'ts (section 6) tie to `PRODUCT.md` anti-references + +### Step 3 - `/impeccable extract` (existing codebases only) + +- [ ] Repeated patterns + hard-coded values consolidated into reusable tokens/components, folded into `DESIGN.md` + +### Step 4 - Refine the weak axis (only what the baseline flags; skip sound axes) + +- [ ] Weak axis addressed: `typeset` (type) - `colorize` (color) - `layout` (rhythm) - `animate` (motion) + +### Step 5 - `/impeccable audit` + `/impeccable critique` + +Validate and capture the backlog. + +- [ ] Contrast: body >=4.5:1, large >=3:1, placeholder >=4.5:1, UI >=3:1; no gray-on-tint; color-blind safe +- [ ] `audit` reports no P0 (a11y, responsive, anti-patterns) +- [ ] `critique` score snapshot + P0/P1 backlog captured + +### Step 6 - Showcase & sign-off + +See the whole system rendered, then validate it. + +- [ ] Design system reviewed visually - `/impeccable live` (in-browser panel: color tiles + component primitives from `DESIGN.md`/sidecar; needs a dev server, renders even day-zero) OR `/impeccable craft "design-system styleguide page"` for a built, shareable showcase +- [ ] Tokens + components match the intended brand; signed off + +**Ongoing (later, not this flow):** evolve via `/impeccable shape` / `craft` / `live` / `harden` / `polish`, re-`critique` to track the trend. + +## Test + +After running: `DESIGN.md` exists at the project root with the six section headers (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) + a token frontmatter block, and `/impeccable audit` reports no P0 contrast failure. Real-execution on disk, never mocked. diff --git a/plugins/aidd-context/skills/12-design-system/actions/02-redesign-page.md b/plugins/aidd-context/skills/12-design-system/actions/02-redesign-page.md new file mode 100644 index 00000000..b2487ffd --- /dev/null +++ b/plugins/aidd-context/skills/12-design-system/actions/02-redesign-page.md @@ -0,0 +1,97 @@ +# 02 - Redesign a page + +An executable playbook: **you (the AI) invoke each Impeccable command yourself** - the user never types one. The user only answers questions and validates results between steps. Walk the steps in order as a todo; each step says what to invoke, what to ask, and when to move on. Impeccable writes the code; `DESIGN.md` stays the single source of truth. + +## Inputs + +- `page` (required) - the page to redesign: a route (`/pricing`), a source path (`src/pages/pricing.tsx`), or a dev-server URL. Prefer a source path; ports drift, paths do not. If missing, ask for it first. + +## Outputs + +- The page restyled by Impeccable against the canonical `DESIGN.md`. +- A `critique` snapshot trail (baseline → final) proving the improvement. +- `DESIGN.md` updated **only via `extract`** - never by hand. + +## Process + +### Step 1 - Check the ground + +**Do:** verify `/impeccable` responds and `DESIGN.md` exists at the project root - and that it has a point of view. + +- If Impeccable is absent: guide install (), then stop. Never emulate it. +- If `DESIGN.md` is absent: run action [01-create-design-system](01-create-design-system.md) first - redesigning without a system just produces new drift. +- If `DESIGN.md` is **generic**, fix it before redesigning - every command aligns the page to it, so a bland system caps the ceiling (polished garbage stays garbage). Generic means any of: no anti-references in `PRODUCT.md`, color strategy Restrained-by-default when the brief wants impact, mood sentence that says "modern/clean". Route to action 01 steps 1-2 (`init` / `document`) to re-found it, then come back. + +### Step 2 - Measure: invoke `/impeccable critique ` + +**Do:** invoke it now - it is the measurement, not an option. It scores Nielsen's 10 heuristics 0-4 (total /40; real interfaces land 20-32), persists a snapshot, and returns the P0/P1 backlog. + +Critique's own flow ends by presenting findings and asking the user targeted questions (it STOPs and calls AskUserQuestion itself). **Let it** - don't summarize over it or re-ask. + +### Step 3 - Complete the brief + +**Do:** critique's questions cover what is broken; add only what they don't, in one AskUserQuestion: + +1. Is the page wrong (structure, content order) or just ugly (style)? - this decides Step 4's route +2. Any direction already in mind? (bolder, calmer, simpler...) + +Critique's answers + these two are the brief for everything below. + +### Step 4 - Fix: invoke one command per weak axis + +**Do:** route from the critique backlog + the user's answers, top severity first. Impeccable's own rule applies: a command is a suggestion the user confirms - name the command and the reason, get a yes, then invoke. One command, show the result, then the next. Skip sound axes. + +**Fix defects** (convergent - removes what is broken): + +| Symptom (critique + user) | Invoke | +| ------------------------------------------- | ----------------------------- | +| Score low across the board, many small P1s | `/impeccable polish ` - it reads the critique snapshot as its backlog | +| Hierarchy flat, spacing off, crowded | `/impeccable layout ` | +| Type generic, sizes arbitrary, hard to read | `/impeccable typeset ` | +| Gray, dull, monochrome | `/impeccable colorize ` | +| Loud, garish, overwhelming | `/impeccable quieter ` | +| Cluttered, competing for attention | `/impeccable distill ` | +| Copy confusing, labels unclear | `/impeccable clarify ` | +| Breaks on mobile / other viewports | `/impeccable adapt ` | + +**Add ambition** (divergent - the score won't flag these; only the user's "still ugly" does): + +| Symptom (critique + user) | Invoke | +| ------------------------------------------- | ------------------------------- | +| Bland, safe, no personality | `/impeccable bolder ` | +| Correct but forgettable, nothing memorable | `/impeccable delight ` | +| Static, lifeless | `/impeccable animate ` | +| "Wow" is the brief, push past conventional | `/impeccable overdrive ` | + +**Convergent vs divergent - the trap:** `critique`/`audit`/`polish` only remove defects. A page can score 30+/40 with zero P0 and still be boring; another polish loop will never fix that. When the score is fine but the user finds the page bland, take the divergent table - and check Step 1's `DESIGN.md` quality gate first, since a bland system caps every command. + +**If the user said "the page is wrong" in Step 3:** invoke `/impeccable shape " redesign"` instead - it runs its own discovery interview and produces a confirmed brief. Don't stack axis commands on a broken foundation. + +Constraint: changes stay within `DESIGN.md` tokens - no new one-off colors, fonts, or spacing values. + +### Step 5 - Show and ask: good direction? + +**Do:** show the result (screenshot, or offer `/impeccable live` for in-browser variant picking if a dev server runs). Ask: keep, adjust, or revert? + +- Adjust → back to Step 4 with the feedback. +- Keep → next weak axis, or Step 6 when the backlog is done. + +### Step 6 - Verify: invoke the quality gates + +**Do:** invoke in order, yourself: + +1. `/impeccable polish ` - alignment, spacing, micro-details (skip if Step 4 already ran it) +2. `/impeccable audit ` - must report no P0 (a11y, contrast, responsive) +3. `/impeccable critique ` - score must beat the Step 2 baseline, no P0/P1 left + +**If a gate fails:** back to Step 4 with the new backlog. Two stalled loops in a row → the problem is structural, go through `shape`. + +### Step 7 - Fold back: keep the doc impeccable + +**Do:** if the redesign produced repeated patterns or new token needs, invoke `/impeccable extract ` so they fold into `DESIGN.md`. Never edit `DESIGN.md` by hand, never create a competing design file (point, never copy). + +**Then tell the user:** baseline → final score, what changed, what was folded back. + +## Test + +After running: the `critique` snapshot trail shows final score > baseline with zero P0, `audit` reports no P0, and `git diff DESIGN.md` is either empty or produced exclusively by `extract`/`document`. Real-execution on disk, never mocked.