Design

Imported from byronwade/Design (AGENTS.md). Install upstream with npx skills add byronwade/Design. Copyright stays with the author.

Agent Operating Protocol

This file governs AI-assisted work in projects that adopt this design SDK.

Mission

Complete the requested work while leaving the affected dependency cone healthier than before. Reuse existing concepts before creating new ones. Reduce duplication, accidental complexity, design drift, and competing sources of truth. Convert recurring objective failures into mechanical checks.

Permission boundary

A repository URL, connected source, @GitHub mention, available write tool, screenshot, or reference project is not permission to edit it.

Classify the operating mode before acting:

• Reference — inspect only; use as evidence; never modify.
• Review — inspect and report; never modify.
• Audit and plan — inspect and produce a self-contained plan; never modify production source.
• Opportunity discovery — identify and prioritize improvements, including rejected candidates; never silently implement.
• Prototype — build isolated alternatives without changing production behavior.
• Implementation — edit only when the user explicitly requested changes.
• Migration/cleanup — perform bounded recursive cleanup only when explicitly requested or required by the accepted implementation.

When intent is ambiguous, choose the least destructive mode.

Authority

Apply instructions in this order:

1. User request and acceptance criteria.
2. Closest project-specific AGENTS.md.
3. Project PROJECT_PROFILE.md.
4. Root DESIGN.md and its constitution.
5. This protocol.
6. Architecture decisions, public contracts, tests, and repository documentation.
7. Existing conventions only when they do not contradict higher authority.

Existing code is evidence of current implementation, not automatic proof of intended design.

Required workflow

For every nontrivial task:

1. Frame behavior, constraints, non-goals, operating mode, and verification target.
2. Read relevant instructions and project profile.
3. Reconnoiter the target, direct callers, dependencies, tests, and comparable implementations.
4. Search repository-wide for semantic equivalents before creating anything.
5. Decide reuse, configure, extend, extract, or create.
6. Implement the smallest coherent solution when writes are authorized.
7. Recursively clean only the task-related dependency cone.
8. Verify with deterministic checks, rendered evidence when UI changed, and full-diff review.
9. Report decisions, reuse, cleanup, checks, and remaining findings truthfully.

For substantial work, record:

Operating mode:
Target and acceptance criteria:
Existing candidates inspected:
Reuse/extend/extract/create decision:
Expected dependency cone:
Verification plan:

Search before creation

Before creating a component, hook, service, utility, formatter, validator, schema, type, client, state container, query, pattern, or abstraction, search for:

• equivalent names, inputs, outputs, invariants, and side effects;
• shared-package exports and internal APIs;
• copies and near-copies in other applications;
• framework/platform capabilities;
• existing dependencies that already solve the problem;
• deprecated implementations whose callers should be migrated;
• tests and canonical examples that reveal the intended contract.

No exact name match does not mean no equivalent exists. Search by behavior and domain meaning.

Reuse ladder

Choose the first sound option:

1. Reuse unchanged when semantics and lifecycle match.
2. Configure or compose through existing variants, slots, callbacks, adapters, children, or data.
3. Extend the canonical owner when the behavior belongs to the same concept.
4. Extract shared behavior when multiple implementations express one stable concept with clear ownership.
5. Create new only when existing concepts differ materially or extension would confuse ownership and evolution.

New code requires a brief reason earlier options were rejected.

Do not merge incidental similarity merely to satisfy DRY. Do not create wrappers that only rename an API or add styling that should be a variant.

UI and design governance

For any task changing UI, UX, copy, styles, tokens, variants, page composition, interaction, marketing presentation, or mobile behavior:

1. Read DESIGN.md and PROJECT_PROFILE.md.
2. Classify the surface: Workbench, Guided, Evidence, Showcase, or Shared.
3. Name the page pattern before changing layout.
4. Inspect the registry, canonical specimens, shared primitives, tokens, tests, and comparable screens.
5. Search across applications before creating a component or visual pattern.
6. Render realistic states and representative viewports.
7. Run the design checks appropriate to the changed surface.

For substantial UI work, extend the decision record:

User and job:
Surface profile:
Named pattern:
Primary object and action:
Existing UI candidates inspected:
Composition decision and rejected alternative:
Disclosure plan:
State coverage:
Responsive and input plan:
Accessibility/performance risks:
Expected files:

UI ownership

• Runtime values belong in token owners, not page-local constants or Markdown copies.
• Product code consumes semantic tokens and canonical component APIs.
• shadcn-compatible primitives are the default base; normalize them once, then reuse the canonical owner.
• Do not hardcode raw colors, arbitrary shadows, radii, motion, z-indexes, or duplicate layout dimensions.
• Do not fork shared component styles by application or brand.
• Do not copy a component across apps because importing or extending the owner requires more investigation.
• Do not add a second icon, form, table, overlay, or motion system.
• Context menus, hover controls, command palettes, gestures, and shortcuts are accelerators, never the only path to critical actions.
• Native controls and established ARIA patterns win over custom behavior.

Agent assembly rule

Product-feature agents assemble. They do not casually design.

Before implementing a page, identify the closest approved pattern and canonical specimen. Build from approved slots. If no pattern can support the required job without distortion, stop feature-level invention and report the missing system capability.

Motion gate

Before adding animation, answer frequency, purpose, speed, interruption behavior, input method, reduced-motion behavior, and whether static feedback would work better.

Use the cheapest capable technique: CSS transition → @starting-style → keyframes → Web Animations API → approved motion library. Never install a motion library for a simple fade or hover. Never use transition: all.

Gesture-driven motion remains interruptible and offers a non-drag alternative when dragging is not essential.

Prototype mode

When a design decision is unresolved, prototypes are isolated decision instruments, not permanent architecture.

• Test one unresolved decision axis per prototype run.
• Create 3 materially different variants by default, 5 maximum.
• Use realistic content and working interactions.
• State the tradeoff of every variant.
• Let the user select the direction.
• Promote only the winner and remove/archive prototype-only code.

Bounded recursive cleanup

Seed a queue with each changed file, symbol, contract, pattern, and test. For each item:

1. Inspect direct callers and dependencies.
2. Search for semantic duplicates and competing sources of truth.
3. Find dead paths, obsolete compatibility code, boundary violations, design drift, and defects exposed by the change.
4. Classify each finding as fix now, migrate atomically, or record.
5. Enqueue only items directly affected by an accepted fix or migration.
6. Repeat until no task-related violation remains.

Fix now when the issue is introduced/exposed by the task, in code already being changed, a correctness/security/accessibility/data-integrity defect, a duplicate implementation of the same concept, dead code revealed by migration, or a small safe verifiable cleanup.

Record instead of fixing unrelated, speculative, broad, risky, or separately-decided work.

Stop when acceptance criteria are met, affected callers are migrated, task-related duplicates and obsolete paths are gone, checks pass, and the next change would be unrelated or disproportionately risky.

Every recursion must reduce a concrete cost: duplication, coupling, obscurity, invalid states, dead code, unsafe operations, failing checks, design drift, or measured resource use.

Architecture and code quality

• Maintain high cohesion, low coupling, explicit ownership, one-way dependencies, and no cycles.
• Keep domain rules in their domain; shared packages do not become dumping grounds.
• Maintain one source of truth for each invariant.
• Prefer language, platform, framework, and existing-library capabilities over custom machinery.
• Prefer direct readable flow over clever compression and needless indirection.
• Do not equate fewer lines with faster or better code.
• Make invalid states unrepresentable when practical.
• Avoid unsafe casts, suppressions, swallowed errors, and disabled rules as shortcuts.
• Delete replaced implementations and temporary shims after migration.
• Before adding a dependency, evaluate overlap, accessibility, maintenance, bundle/runtime cost, framework compatibility, and removal of displaced code.

Performance

Performance claims require evidence: baseline → measure below the symptom → identify bottleneck → smallest responsible change → repeat measurement → preserve a budget when regression risk matters.

Prioritize algorithms, query behavior, network trips, serialization, caching, client JavaScript, rendering, allocations, concurrency, and hot-path I/O before syntax micro-optimization.

Testing and verification

Test observable behavior and public contracts. Add characterization tests before risky refactors and regression tests for defects when practical.

For UI, verification includes behavior, keyboard, focus, touch, responsive reflow, accessibility tree, reduced motion, realistic state coverage, and visual evidence. A polished screenshot alone is not completion.

Run checks from narrowest to broadest. Never weaken a valid test merely to pass a change. Never claim a check ran when it did not.

Mechanical prevention

When an objective failure can recur, add the smallest reliable sensor: type invariant, linter/AST rule, forbidden import, dependency boundary, duplicate detector, dead-code check, contract/regression/architecture test, accessibility check, visual baseline, or performance budget.

For existing debt, record a baseline, block new violations, and reduce the baseline when touched.

Required final report

• Decision
• Reused
• Created or extended
• Recursive cleanup
• Mechanical prevention
• Verification
• Design evidence for UI work
• Remaining findings

Never

• edit a reference repository without explicit permission;
• create before searching;
• copy-paste shared implementations across applications by default;
• reimplement canonical helpers locally;
• force unrelated concepts together merely to satisfy DRY;
• create wrappers with no invariant or meaningful simplification;
• perform unbounded cleanup during focused work;
• optimize without measurement;
• suppress types, lint, tests, security, accessibility, or errors without justified exception;
• leave old and new implementations competing after migration;
• call design complete because one screenshot looks polished.