ui-engineering

Files (5)

• SKILL.md
• accessibility.md · references/
• design-system.md · references/
• storybook.md · references/
• verification.md · references/

SKILL.md (first lines)

# UI Engineering Orchestrator

Use the smallest workflow that can produce trustworthy evidence. Route to specialist skills instead of duplicating their rulebooks here.

## Scope

- **Trivial:** copy tweak, obvious isolated CSS defect, tiny prop/style correction. Fix directly; do not summon the full stack.
- **Focused UI:** one component or interaction. Inspect local conventions, use only relevant specialists, update reusable-component evidence, verify the changed behavior.
- **Substantial UI:** new surface, major feature, redesign, design-system work, multi-component flow. Use the orchestration below.
- **Review-only:** preserve scope and use independent review/evidence rather than redesigning by default.

If project infrastructure needed for a substantial task is missing, tell the user to run `/ui-setup`; do not silently mutate project tooling from the orchestrator.

## 1. Recon before direction

For substantial work in an existing repository, map the actual system before changing it: framework/package manager, styling architecture, tokens/theme, reusable components, Storybook, Playwright, shadcn configuration, responsive/motion conventions, and the running UI when available.

Use `ui-recon` or `ui-design-system-audit` for large read-only exploration. Separate intentional product decisions from accidental drift.

## 2. Design direction

Invoke the internal `ui-design-direction` skill for a new surface or meaningful redesign. It classifies the surface and produces a compact direction contract covering expressive dials plus operational constraints such as task frequency, information criticality, error cost and data complexity.

Translate accepted direction into reusable system decisions. Read `references/design-system.md` for substantial token/component-system extraction or normalization.

## 3. Component engineering

Search in this order:

1. existing project component;
2. existing project primitive;
3. already-installed component library;
4. shadcn/ui and configured registries when the project uses or has deliberately selected shadcn;
5. another trusted compatible source;
6. small custom implementation only when previous options do not fit.

When shadcn is active, invoke `ui-shadcn`. Preserve `components.json`, its base library, aliases, icon library, registries and styling architecture unless migration is explicitly requested. Registry components are implementation material, not a second visual identity.

## 4. Storybook is core for supported web frontends

For harness-managed supported web frontend work, reusable components added or materially changed should receive meaningful Storybook stories in the same task. Storybook is the isolated component workbench for states, interaction examples, documentation and automated a11y evidence.

Do not force Storybook 10 into an unsupported/legacy target or ambiguous monorepo root. Read `references/storybook.md` for policy and compatibility.

## 5. Specialist routing

### Motion
`ui-design-direction` owns overall motion character; invoke `ui-motion` for detailed motion behavior. Prefer CSS when sufficient and respect reduced motion.

### React / Next.js engineering
Invoke `ui-react-engineering` when React/Next changes materially affect data fetching, rendering, server/client boundaries, bundle size, rerenders or performance. Do not turn every UI task into theoretical optimization.

### Independent interface review
After substantial implementation stabilizes, review from a fresh read-only context. Invoke `ui-interface-review` for a fresh read-only review. Findings are evidence, not automatic rewrite commands.

## 6. Browser truth

Use the repository's existing Playwright Test suite for repeatable flows. If `playwright-cli` is installed and available, it is appropriate for token-efficient exploratory browser work; do not conflate Playwright Test's `npx playwright` test CLI with the separate coding-agent `playwright-cli` package.

Select verification based on introduced risk:

- build/type/lint for code integrity;
- Storybook for isolated states;
- Storybook a11y for component-level automated accessibility checks;
- Playwright Test and/or `playwright-cli` for real interactions and responsive behavior;
- `@axe-core/playwright` for automated accessibility evidence;
- manual keyboard, focus, zoom and reduced-motion checks where automation cannot prove behavior.

Read `references/verification.md` and `references/accessibility.md` when needed. Fix root causes and rerun failed checks.

## 7. Completion contract

For substantial UI work, do not claim completion until applicable evidence supports that:

- requirements and intentional existing behavior are preserved;
- implementation extends rather than forks the design system;
- reusable Storybook coverage is current where supported/applicable;
- relevant responsive behavior is inspected;
- changed interactive UI has keyboard/focus semantics checked;
- relevant automated accessibility checks pass;
- critical changed flows were exercised in a real browser;
- motion is purposeful and reduced-motion aware;
- no known runtime/console error caused by the change remains;
- accepted independent-review findings were fixed and rechecked.

Report what was actually verified and meaningful limits. Never imply untested coverage.

## 8. Context discipline

Do not invoke every specialist for every task. Skill bodies persist after loading. Route narrowly, isolate read-heavy review/recon work with forked skills, and prefer environment evidence over more prose rules.

From hersti/ui-engineering, MIT.

More from hersti/ui-engineering