designing-in-patterns
Use when designing, planning or auditing UI against a component library — naming surfaces with the repo's pattern vocabulary, deciding reuse versus extend versus new, exploring compositions, or writing the reuse table (component-plan.md, a spec's `## Reuse`, a UI audit). Carries the design method; the repo's own vocabulary, bundle and board rules come from project-context and the designer override.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- designing-in-patterns
- description
- Use when designing, planning or auditing UI against a component library — naming surfaces with the repo's pattern vocabulary, deciding reuse versus extend versus new, exploring compositions, or writing the reuse table (component-plan.md, a spec's `## Reuse`, a UI audit). Carries the design method; the repo's own vocabulary, bundle and board rules come from project-context and the designer override.
03 SKILL.md 正文
designing-in-patterns — design method
Core principle: a screen is assembled from components that already exist. The library moves before the screen, and every decision to add a component is made once, here, by the designer — never by whoever builds the screen.
Announce at start: "I'm using the designing-in-patterns skill."
Repo-specific values (the vocabulary file, the bundle inventory folder, templates, board lint) are never named here: read them from the project-context ## Design tokens and .claude/project/agents/designer.md.
1. Name every surface
surface := every visible thing on a board or in a spec, one row per surface per screen
name := a pattern from the `Pattern vocabulary` file, or `?` — never an invented name; on a wireframe it is the `data-pattern="<name>"` tag of the block, never a visible label
counts := a name counts only when the `Bundle inventory` folder has that component (ls/Grep, never by reading component source)
vocabulary names a component the inventory lacks -> the surface is `?`, not that pattern
2. Two tests before a ? becomes new
second occurrence := Grep the app's UI paths for the pattern
present once as page code -> it is shared now: shared component AND a cleanup task in the same story ("Replace <path> with <Component>")
slot := different children in an existing component meet the need -> reuse, note the slot; not new
neither applies -> new
3. Extend or new
extend := a new option on an existing component: a tone, a size, a slot
new := a different structure or behaviour
An extension that needs a second rendering path inside the component is new; a new component that is the old one plus one option is an extension.
4. Explore rows
A row whose composition or feel the vocabulary does not settle is Explore: yes.
2-3 shadcn compositions, each with phone and desktop behaviour and the keyboard behaviour they share
built as Storybook variant stories on the library branch (the `Component review` token serves them)
the human chooses before merge; losers are deleted in the same PR; only the winner reaches the bundle
never drawn by hand on a board
5. Reuse table
One format for component-plan.md and a spec's ## Reuse:
| Surface | Pattern | Template | Component | Action | Explore | Story |
| Column | Content |
|---|---|
| Surface | the visible thing as named on the draft (its data-pattern tag marks the pattern; ? marks a gap) |
| Pattern | a vocabulary name; ? only while unsettled, never in a committed plan |
| Template | the page template; — when the surface is not a page |
| Component | the bundle export (PascalCase); — when none |
| Action | reuse · extend · new |
| Explore | yes · no |
| Story | the library story key; — for reuse |
A new row with no Story is an open question; the spec cannot be approved with it.
5a. Controls inside a surface
A pattern name settles the block, not what is drawn inside it. Before a plan is final, every distinct control and every list or table row structure is checked against the real bundle and library.
verdict := reuse (a named export) | shadcn (a named ui part) | in source, not exported | compose (named parts; shared already or not) | missing
anything but reuse | shadcn -> an open question with options and a recommendation; the human decides: extend, build new, export, accept the composition, or drop
a container being in the bundle says nothing about its rows, cells or items: check them by name
Table format and the rule: refs/component-plan.md "Controls checked".
6. Layering rules (the method respects these)
slots not settings := variation comes through children and slots, not a growing list of props
no data in layers 1-4:= primitives, ui components, composites and layouts take values by props; no fetching, no domain types
build downward := a surface is built from layers below it; a higher layer never re-implements a lower one
shared the second time:= the second use of a pattern makes it shared (test 2)
everything in the bundle:= a component not exported to the design bundle does not exist for boards
7. Anti-patterns
| Anti-pattern | Instead |
|---|---|
| Naming a pattern the bundle lacks | Mark the surface ? and run the two tests |
| A screen board introducing a component | Raise the library story first; the board mounts the bundle |
| className restyling of a shared component | Change the component for everyone (extend), or reuse it unchanged |
| A copy kept to pass a board | Fix the board or the component; never keep the copy |
| Choosing the composition by hand-drawing it | Explore row: variant stories, human picks |
04 同仓库更多 Skills
typeorm
Use when defining TypeORM entities, writing migrations, or building repository/query-builder code in TypeScript. Covers entity and relation decorators, the Data Mapper pattern, migrations, the query builder, transactions, and multi-database configuration.
hono-api
Use when building or extending REST APIs with Hono + @hono/zod-openapi. Covers schema-first route declaration with createRoute, feature-grouped composable routers, a class-based service layer behind interfaces, the strategy pattern for multi-event webhooks, typed request validation, and auto-generated OpenAPI docs.
electrodb
Use when defining DynamoDB entities, modeling indexes, or writing queries/mutations with the ElectroDB ORM. Covers entity schema, access patterns, CRUD operations, update expressions, and single-table design patterns.
atomic-design
Use when structuring or decomposing any frontend UI into reusable components, regardless of framework. Applies Brad Frost's atomic design methodology — atoms, molecules, organisms, templates, and pages — to guide consistent component hierarchy, naming, and composition decisions.
writing-docs
Use when writing, restructuring, or reviewing any prose documentation — a tutorial, how-to guide, reference page, or explanation/conceptual doc — for a public docs site (e.g. Mintlify MDX, docs/, README material), a getting-started guide, an API/CLI reference page, or a "why we built it this way" conceptual page. Applies the Diátaxis framework (see https://diataxis.fr/) — every document belongs to exactly one of the four quadrants (tutorial / how-to guide / reference / explanation), and mixing quadrants inside one document is the single most common documentation failure. Covers the four-quadrant compass for picking the right form, per-quadrant structure templates, an anti-pattern list for quadrant drift, and generic voice/craft rules — repo-specific voice and target output format (e.g. Mintlify MDX) are resolved from the repo's docs-manifest (falling back to project-context), never hardcoded here.
writing-adrs
Use when authoring an Architecture Decision Record (ADR) — a short document that captures one significant, hard-to-reverse technical or architectural decision, its context, and its consequences. Triggered by the sdlc ADR pipeline (the knowledge-engineer agent behind /sdlc:docs seed adr and /sdlc:docs distill) when generating an ADR from a story, and by anyone hand-authoring an ADR under docs/adr/ today. Covers why ADRs are kept short and inverted-pyramid, the required sections (Title, Status, Decision, Context, Alternatives Considered, Consequences), the proposed→accepted→superseded (or →rejected) status lifecycle and the never-edit-only-supersede immutability rule, the NNNN-decision-slug.md filename convention, and the ADR frontmatter fields (status, agents, source-stories) the pipeline reads to route a generated ADR into docs/adr/index.md.