@etus/seven-skill

Seven Design System skill, plugin, and CLI detector for AI coding agents.

This package distributes the Seven Design System guard-rails as a Claude Code plugin and a deterministic CLI detector. Phase 2 expands to Cursor, Codex, Gemini, OpenCode, and other AI harnesses.

What ships

• Skill source-of-truth under source/: the routing SKILL.md plus domain references for typography, color, motion, spatial design, voice, and the Phase 1 sub-commands (shape, audit, polish, clarify).
• Multi-harness build pipeline in build/ that emits one configured skill per target harness. Phase 1 ships Claude Code only at .claude/skills/seven/.
• Claude Code plugin wrapper in .claude-plugin/ with plugin.json and marketplace.json auto-synced from package.json.
• Deterministic CLI detector in cli/ with 35 Seven-tuned rules (npx seven detect <path>).

Status

Phase 1 — hardened Claude Code port. Claude Code target only, 35 detector rules, four sub-commands. Distributed as a Claude Code plugin via the marketplace configuration in this package and as an npm CLI/skill package.

Install

Claude Code plugin (recommended)

The plugin is configured by .claude-plugin/marketplace.json and .claude-plugin/plugin.json in this package. Inside the Seven monorepo it is available as a workspace dependency:

pnpm add -D @etus/seven-skill --workspace

For external projects, install the package or point the plugin manifest at the git source:

pnpm add -D @etus/seven-skill
claude plugin install @etus/seven-skill

# Git source fallback while marketplace propagation catches up:
claude plugin install github:etusdigital/seven#path=packages/seven-skill

CLI detector

Inside the monorepo:

pnpm --filter @etus/seven-skill exec seven detect packages/ui/src/

Commands (Phase 1)

| Command | Purpose | | ---------------- | -------------------------------------------------------------------------- | | /seven shape | Plan UX shape before writing component code | | /seven audit | Five-dimension scan: a11y, performance, theming, responsive, anti-patterns | | /seven polish | Final-pass cleanup aligned to Seven tokens and conventions | | /seven clarify | UX copy in pt-BR: imperative leads, sentence case, no trailing periods |

Phase 2 adds craft, harden, layout, typeset.

Detector rules

The detector ships 35 rules across three engines (regex, static-html, browser). Each rule is quality (real design / a11y drift) or slop (an AI tell, Seven-flavored). The full catalog — every rule with its justification, a wrong/right example, and the design reference that grounds it — is in docs/detector-rules.md.

Token-aware. Eight rules are grounded in Seven's real design tokens: a build step (build:tokens) reads @etus/tokens and embeds a token-data snapshot, so hardcoded-color-not-token names the exact token a literal maps to, non-inter-font reads the font tokens, radius-mixed-scales reads the radius scale, and bounce-easing knows the sanctioned easing tokens. When @etus/tokens rebuilds from a Figma sync, regenerate the snapshot. The other 27 rules are heuristics — language facts, CSS mechanics, and a11y standards no token defines. Each rule's verdict is in RULE_GROUNDING.

Quick map: nine text rules (non-inter-font, hardcoded-color-not-token, raw-tailwind-palette-color, missing-color-type-hint, missing-length-type-hint, leading-none-with-length-var, fuchsia-in-ui-chrome, pt-pt-vocab, pure-black-or-white); three inverted from impeccable (side-stripe-border, gradient-text-decorative, shadows-not-borders); seventeen universal design-quality / a11y rules; six Seven-specific element rules (missing-tactile-press, pill-on-button, radius-mixed-scales, non-lucide-icon, emoji-in-chrome, forbidden-em-dash).

Exit codes follow the impeccable convention: 0 clean, 2 findings present, 1 usage error.

Architecture

packages/seven-skill/
├── source/                # authoring source (not shipped to npm)
│   ├── SKILL.md           # router + shared design laws
│   ├── reference/         # domain + sub-command references
│   └── scripts/           # consumer-side runtime scripts (Phase 2)
├── build/                 # multi-harness build pipeline (not shipped)
├── cli/                   # deterministic detector (shipped)
├── .claude/skills/seven/  # Claude Code build output (shipped, tracked)
├── .claude-plugin/        # Claude Code plugin wrapper (shipped)
└── tests/                 # unit + fixture tests

Author in source/. Run pnpm --filter @etus/seven-skill build to regenerate the per-harness skill outputs and the plugin manifest.

Development

pnpm --filter @etus/seven-skill build       # regenerate harness output and manifests
pnpm --filter @etus/seven-skill test        # vitest unit + fixture suite
pnpm --filter @etus/seven-skill typecheck   # tsc strict mode

# Detector usage
pnpm --filter @etus/seven-skill exec seven detect path/to/file-or-dir
pnpm --filter @etus/seven-skill exec seven detect packages/ui/src/ --json
pnpm --filter @etus/seven-skill exec seven help

License

Apache-2.0. See LICENSE.