Pattern classifier

A structured conversation for integrating patterns into the library. Three phases: articulate & map (what is this, does it already exist?), classify (where does it go?), enrich (research, write, update neighbours).

Conceptual foundations

Three documents ground the reasoning. Read them before proceeding if you haven't already in this conversation.

• •

  resources/semilattice.md — the pattern system is a semilattice, not a tree. The sidebar forces single placement; cross-references, tags, and the graph capture the overlapping memberships that the tree suppresses. Every tree placement is lossy; the question is which loss is least harmful.

• •

  plans/2026/march/activity-theory-reorg.md — the AT hierarchy (operations → actions → activities) organises by where attention lives. Operations are automatic and condition-driven. Actions are conscious and goal-directed. Activities are motive-driven and strategic. This replaced the Atomic Design hierarchy as the primary sidebar projection.

• •

  src/stories/foundations/Interaction.mdx — the intent lifecycle (trigger → seeking → evaluation → sense-making → application → sharing) provides sub-grouping within actions. Actions are filed under the lifecycle stage they primarily serve; tags and graph edges capture the stages they also touch.

Two generated JSON files provide queryable views of the library:

• •

  src/pattern-graph.json — nodes (id, title, category, path) and edges (source, target). Use for neighbourhood scanning: given a candidate pattern, find what it would connect to by checking existing edges to/from related nodes. Edges are currently untyped (no precursor/complementary distinction).

• •

  src/activity-levels.json — per-node metadata: activity-level, lifecycle-stage, atomic-category, mediation. Use for classification checks: see how neighbours are classified, spot level mismatches, find patterns in the same lifecycle stage.

Both are generated by scripts/extract-graph-data.ts from <Meta> tags and cross-references in MDX files. They reflect the current state of the library — read them early in the process to ground decisions in actual topology rather than assumptions.

Scope: what belongs in this library

This library is design repertoire — recurring interaction structures between actor and system that a designer can recognise, name, and reach for when shaping an interface. Before classifying, verify the incoming knowledge is repertoire rather than one of the adjacent knowledge types that inform or use patterns but live elsewhere.

The test

Ask: can a designer apply this directly when composing an interface? A pattern describes something you place, arrange, or orchestrate in a design. If the knowledge instead describes why something works, how to discover what to design, or how to evaluate what you designed, it's a different kind of knowledge.

Adjacent knowledge types

Theory — explanatory models and perceptual/cognitive laws (Fitts's Law, Hick's Law, Gestalt principles, distributed cognition). These explain why patterns work but aren't themselves placeable in a UI. They belong in references, not as pattern pages. However, they should be cited from patterns they inform — a pattern's design considerations might invoke Fitts's Law to explain a sizing trade-off.

Use qualities — cross-cutting properties like responsiveness, accessibility, progressive disclosure, forgiveness. These describe how patterns should behave rather than being patterns themselves. Some already live in foundations. The test: if it modifies a noun ("responsive layout", "forgiving form") rather than being the noun, it's likely a quality. Qualities that manifest as distinct, recognisable interaction structures can also be patterns — progressive disclosure is both a principle and an observable pattern. When this happens, the pattern page describes the interaction structure; the principle lives in the references that inform it.

Process and methods — how you discover, evaluate, or deliver designs. These are about the practice of designing, not the substance of what gets designed. They belong in a methods repository or process documentation, not here.

Research findings — empirical results, user insights, experimental data. Raw material that feeds into patterns. The "from research" entry point already handles this: the expected outcome is enrichment of existing patterns, not a new pattern page for the finding itself.

When it's ambiguous

Some things genuinely straddle the boundary. Signals to look for:

• •If it has an observable interaction structure (actors do something, the system responds in a recognisable way) → it has a pattern dimension, even if it's also a principle or quality. Document the interaction structure as a pattern; reference the theoretical dimension.
• •If it only makes sense as a modifier of other patterns (it changes how they behave but has no independent manifestation) → it's a quality or foundation, not a standalone pattern.
• •If it's primarily a framework for organising other patterns → it's a foundation or a conceptual tool, not a pattern. It might warrant a foundations page, but not a pattern page.

When genuinely uncertain, surface the ambiguity to the user rather than forcing a classification. The skill is a conversation, not a gate.

Entry points

The process adapts to how the work arrives. Three common scenarios:

From practice

"I designed an interaction and want to document it for future reference."

Start with articulation: describe the interaction in terms of what problem it solves, what the actor experiences, and what design decisions were involved. Then map against existing patterns — the thing you built may already have a name in the library, or it may be a combination of existing patterns rather than a new one. Only proceed to classification if mapping reveals something genuinely unrepresented.

From research

"I read a paper and want to integrate its findings."

Start with extraction: what are the key findings, frameworks, or design implications? Then map each finding to existing patterns it informs. The most common outcome is enrichment — updating existing patterns with new sections, design considerations, or references — not creating new patterns. Only create a new pattern if the research describes an interaction that has no home in the current library.

From a gap

"There's an established pattern that's missing from the project."

Start with verification: search the library broadly (names vary; the concept might be covered under a different term or absorbed into a broader pattern). Check the graph neighbourhood where you'd expect it — what's already there? If the gap is confirmed, articulate the pattern clearly before classifying it.

Phase 1: Articulate & map

Before classifying, understand what you're working with and how it relates to what exists.

Articulate

Write a one-sentence relational definition: what does this pattern do in the relationship between actor and system? Avoid implementation descriptions ("a dropdown that...") — describe the interaction ("narrowing a set of options through...").

If the pattern resists a clean one-sentence definition, it may be multiple patterns or an aspect of an existing one.

Map against existing patterns

Search broadly. Check:

• •Patterns with similar names or synonyms
• •Patterns that serve the same user need
• •Patterns whose "Related patterns" sections describe this concept without it having its own page
• •Commented-out sections ({/* */}) in existing patterns that sketch this territory

Read the candidates. The mapping produces one of five outcomes:

1. •Already exists — the pattern is covered. The work is enrichment (add examples, references, design considerations to the existing pattern). Skip to Phase 3.
2. •Partially covered — aspects are spread across multiple existing patterns, but the unifying concept isn't represented. Consider whether a new pattern, an umbrella, or just better cross-references would serve best.
3. •Distinct and new — genuinely unrepresented. Proceed to Phase 2.
4. •Existing pattern needs splitting — the mapping reveals that an existing pattern is too broad and this concept deserves to be separated out. Proceed to Phase 2 with attention to what stays and what moves.
5. •Not design repertoire — the candidate is theory, method, quality, or implementation convention rather than an interaction pattern (see Scope above). The work is either referencing it from the patterns it informs, or directing it to where it belongs. Surface this to the user with a recommendation for what to do with the knowledge instead.

Phase 2: Classify

Work through these questions in order. Each may change the answer to later ones. Present findings to the user as you go — this is a conversation, not a report.

1. Neighbourhood: what does this connect to?

Before deciding where something goes, understand what it touches.

• •List the candidate edges: what would this pattern link to in its Related Patterns section? What existing patterns would link back?
• •A pattern with edges mostly to operations-level patterns probably belongs in operations. A pattern whose neighbours span multiple AT levels might be a quality or a foundation rather than a pattern at a specific level.

The neighbourhood determines almost everything else.

2. Granularity: one pattern or several?

The test is graph topology, not document length.

Split when:

• •The sub-patterns have distinct neighbourhoods — different sets of related patterns, different use contexts, different design concerns
• •Each sub-pattern could be meaningfully linked to from other patterns (other patterns would want to reference autocomplete specifically, not "assisted task completion" generically)
• •The sub-patterns sit at different AT levels or lifecycle stages

Keep unified when:

• •The sub-patterns are always used together (compositional binding, like DataView's table/card/filter)
• •The relationships are mostly shared — other patterns link to the group, not to individual members
• •Splitting would create nodes too thin to justify their own page

When splitting, also decide the umbrella strategy (see step 5).

3. AT level: where does attention live?

Apply Leontiev's hierarchy:

• •Operation — the actor doesn't consciously attend to this. It works automatically, is condition-driven, and becomes invisible through habituation. Test: would a skilled user describe this as something they "do", or something that "just happens"?
• •Action — the actor consciously engages. They know what they're trying to achieve and deliberately choose how. Test: does this require focal awareness and a goal?
• •Activity — shapes how work unfolds over time, coordinating multiple actions. Motive-driven, strategic. Test: does this describe why and how work proceeds, rather than what the actor does in a moment?

Watch for level ambiguity:

• •Some patterns shift levels through habituation (autocomplete starts as conscious action, becomes operational). File where the design challenge lives — if the design work is about making it invisible, it's operational.
• •Some patterns straddle levels (toolbar is both operational affordance and action container). The tree picks one; tags capture the other.
• •Cross-cutting concerns that describe levels rather than sitting at one belong in qualities or foundations.

4. Lifecycle stage (actions only): where in intent resolution?

If the pattern is an action, determine which stage of the intent lifecycle it primarily serves:

• •Seeking — retrieving and gathering information
• •Evaluation — assessing relevance and value
• •Sense-making — synthesising and organising insights
• •Application — taking decisions, completing tasks
• •Coordination — orchestrating shared work

Many actions serve multiple stages. The tree picks the primary stage; add lifecycle:* tags for secondary stages. If the pattern serves all stages roughly equally, that's a signal it might not be an action — reconsider AT level.

5. Umbrella strategy

Three kinds of umbrella exist in the system:

Standalone umbrella — both a pattern in its own right and a container for sub-patterns. Example: Suggestion is a meaningful pattern (system-generated recommendations) that also frames sub-topics (input assistance, relationship suggestions, proposing solutions). Test: does the umbrella have its own design concerns, its own "when it works / when it fails", its own neighbourhood beyond just aggregating the children?

Structural umbrella — exists only to frame and connect sub-patterns. Example: Navigation overview frames the navigation models but isn't itself a pattern you'd apply. Test: would removing this and relying on cross-references between the children lose something? If the umbrella's value is purely "these things form a group", cross-references and tags might suffice.

Implicit umbrella — the relationship between patterns is real but doesn't need its own node. The connection exists in cross-references and graph edges. Test: would anyone navigate to this umbrella, or would they always go directly to a specific sub-pattern? If the latter, the umbrella might not need to exist as a page.

When an umbrella is warranted, decide its placement:

• •If the umbrella is a standalone pattern, it gets its own AT level and lifecycle stage like any other pattern
• •If it's structural, place it alongside its children (e.g., Navigation overview lives in actions/navigation/)
• •Consider whether the umbrella's Meta title should create a Storybook folder grouping (e.g., Actions/Application/Assisted task completion/Autocomplete) or whether children should be siblings with cross-references

6. Tags and metadata

Every pattern needs:

• •activity-level:operation|action|activity — AT level
• •atomic:primitive|component|composition|pattern — retained from Atomic Design as secondary classification
• •lifecycle:seeking|evaluation|sensemaking|application|coordination — for actions, primary stage (and secondary via additional tags)
• •mediation:individual|collaborative — whether the pattern involves multiple actors

Consider additional tags for graph clustering:

• •Domain tags (e.g., ai, navigation-structure, async) that enable faceted filtering
• •These should emerge from existing clusters in the graph, not be invented speculatively

7. Graph impact

Before finalising, consider the topology:

• •What edges does this create in src/pattern-graph.json? (The graph is derived from cross-references, so this is really asking: what will the Related Patterns section look like?)
• •Does this node clarify the graph or clutter it? A node with 2 edges might not justify its existence. A node with 20 edges might be too broad and need splitting.
• •Does this create or join a meaningful cluster? Check whether the neighbourhood forms a recognisable group or scatters across unrelated areas.

8. Propose placement

Synthesise the answers into a concrete proposal:

• •File path(s) and Meta title(s)
• •Tags
• •Umbrella strategy (if applicable)
• •Key edges (Related Patterns sections — at least precursors, complementary, follow-ups)
• •Any existing patterns that need updating (new cross-references, absorbed content, redirects)

Present this as a recommendation for the user to evaluate, not a fait accompli. The semilattice means there's always more than one defensible placement — name the trade-offs.

Phase 3: Enrich

Once the destination is clear — whether it's a new pattern or an update to existing ones.

Research

Before writing, gather substance:

• •Search for academic references (CHI, CSCW, DIS, UIST proceedings; HCI journals)
• •Check practitioner sources (Nielsen Norman Group, Baymard Institute, design system documentation from major platforms)
• •Look for named implementations (how do Salesforce, Google, Apple, etc. handle this pattern?)
• •Identify tensions and trade-offs — these are more generative for design than best practices

Research should inform the pattern's design considerations, not just fill a references section.

Write or update

For new patterns, follow the documentation standards in .claude/rules/documentation.md. Focus on:

• •The relational definition (one sentence after the # Title)
• •Design considerations structured around tensions and trade-offs rather than prescriptive rules — these are what make patterns generative for actual design work
• •Cross-references woven into prose, not just listed in Related Patterns

For enrichment of existing patterns, the changes might be:

• •New sections (e.g., adding "Fixation risk" to Suggestion after reading a paper)
• •Updated design considerations based on new evidence
• •Additional references
• •New cross-references to or from the updated pattern

Update neighbours

Adding or changing a pattern changes the topology. Check:

• •Do any existing patterns need new cross-references to this one?
• •Does this pattern absorb content from an existing stub or redirect? (e.g., patterns/Autofill.md)
• •Do overview pages (e.g., actions/Overview.mdx) need updating?
• •After writing, regenerate the graph data: npx tsx scripts/extract-graph-data.ts

What this skill is not

• •Not a mechanical migration tool (use pattern-migrator)
• •Not a documentation template (see .claude/rules/documentation.md)
• •Not a style guide (see .claude/rules/documentation.md for writing conventions)
• •Not a gate — the user makes the final call. This skill surfaces considerations and trade-offs; it doesn't enforce rules. The system is a semilattice; any tree placement is a compromise, and reasonable people can disagree about which compromise is best.