Echo DS design skill

An agent skill that builds and reviews UI with Echo DS, the Swisper design system. It knows every @swisper.ai/ui, @swisper.ai/web-chat-ui, @swisper.ai/web-file-preview and @swisper.ai/web-map component, the scenarios, the tokens, and the icons, because its references are generated from this repository. It picks the right component for an intent, composes screens from real exports and stories, writes token-only Tailwind, and reviews code, screenshots, or Figma frames with cited, severity-tagged findings.

It replaces packages/design-system/src/DESIGN.md.

Install

The installable skill is the echo-design/ folder. Everything around it (the generator, package.json, these docs) is dev tooling and is not installed.

Inside this repository

Skills live in .agents/skills/, and .claude/skills/, where Claude Code reads project skills, holds a symlink to each. Both entries for this skill are gitignored here. Link it once per clone:

ln -s ../../packages/echo-design-skill/echo-design .agents/skills/echo-design
ln -s ../../.agents/skills/echo-design .claude/skills/echo-design

Use the symlink, not npx skills add, in this repository: the CLI copies files, so the installed copy goes stale every time you regenerate the references or edit SKILL.md.

In a product repository

npx skills add https://github.com/Fintama/fintama/tree/main/packages/echo-design-skill/echo-design
npx skills add https://github.com/Fintama/fintama/tree/main/packages/echo-design-skill/echo-design -a claude-code   # one agent only
npx skills add https://github.com/Fintama/fintama/tree/main/packages/echo-design-skill/echo-design -g               # user-wide

The repository is private, so the machine needs GitHub access to it. The skills CLI supports Claude Code, Codex, Cursor, Windsurf, OpenCode, and others. Without the CLI, copy echo-design/ to .claude/skills/echo-design/ (Claude Code) or point your agent's rules file at echo-design/SKILL.md, as .cursorrules does.

The skill triggers on UI work and design-review requests, and is also available as /echo-design.

Use it

• "Add a delete-workspace flow to the Foundry settings page"
• "Which component should I use for picking one of three views?"
• "Review this PR's UI against Echo DS"
• "Audit apps/web/src/features/billing for hardcoded colours and spacing"
• "Turn this Figma frame into Echo components"
• "Is this empty state right for Swisper?"

What it does

Build mode pins down the product family and audience, then works through these steps:

1. Match a scenario (for example destructive action, form submission, or loading state).
2. Pick components from the selection table, using only their real exports.
3. Compose from the Storybook stories.
4. Write token-only classes on the 1px spacing scale.
5. Cover loading, empty, error, and disabled states, with a @swisper.ai/ui-only fallback when the app has no web-chat-ui.
6. Self-review with the scan, then render the screen and look at it.

Gaps are marked TODO(echo-ds) and reported, not invented.

Review mode goes through five lenses in order:

1. Accessibility
2. System fidelity (tokens, primitives, packages, exports)
3. Selection and composition
4. Interaction and states
5. Content and copy

Every finding has a What, a Why that cites file.md › Heading, and a Fix written as real code. The report ends with a list of system gaps to escalate.

echo-design/scripts/scan-ui.mjs gives both modes a mechanical sweep. It finds hardcoded colours, arbitrary values, spacing numbers that silently render at n × 4px, colour classes that aren't Echo tokens, foreign icons, raw elements, clickable divs, unlabeled icon buttons, generic button labels ("Submit", "OK"), and Title Case copy:

node packages/echo-design-skill/echo-design/scripts/scan-ui.mjs apps/web/src

What's inside

echo-design-skill/                  # workspace package, dev only
├── AGENTS.md                       # operating and contributor manual
├── .cursorrules                    # Cursor entry point
├── scripts/
│   └── build-references.mjs        # regenerates echo-design/references/ from the monorepo
└── echo-design/                    # the skill: the only folder that gets installed
    ├── SKILL.md                    # stance, principles, selection table, Build and Review modes, report format
    ├── scripts/
    │   └── scan-ui.mjs             # code sweep for mechanical findings
    └── references/
        ├── lookup.md               # generated routing table, undocumented components, doc drift
        ├── foundations.md          # hand-written global rules (formerly DESIGN.md)
        ├── packages.md             # hand-written package map, styles setup, spacing scale
        ├── components/ui/          # generated, one per @swisper.ai/ui component
        ├── components/chat/        # generated, one per @swisper.ai/web-chat-ui component or layout
        ├── components/files/       # generated, one per @swisper.ai/web-file-preview component
        ├── components/map/         # generated, one per @swisper.ai/web-map component
        ├── scenarios/              # generated, one per scenario
        ├── tokens/                 # generated colour, spacing, radius, breakpoint, and font tokens
        └── icons.md                # generated @swisper.ai/icons index

Keeping it current

The references are generated, so fix the source (a component's <name>.json, a scenario, the theme) and regenerate:

pnpm --filter @swisper.ai/echo-design-skill generate
pnpm --filter @swisper.ai/echo-design-skill check     # exit 1 when references are stale

AGENTS.md lists the checks to run before committing.