feat(skills): add design-system skill

[myelinated-wackerow]

Summary

Establishes .claude/skills/design-system/ as the canonical knowledge base for UI work in this repo. The skill follows the agentskills.io specification: a SKILL.md entry point with references/ for progressive disclosure.

The goal is to make UI work consistent: when an agent (or human) builds a feature, they get a single source of truth for which components to use, where tokens live, how RTL/i18n works, where the server/client boundary should fall, and the "use a variant, not a new component" pattern.

This is the foundation. Cleanup work to align existing components with these conventions will follow as separate tracked issues.

What's in this PR

• .claude/skills/design-system/SKILL.md -- entry point: top rules, highest-value gotchas, "where do I import from?" cheatsheet, "load this reference when..." map, pre-merge checklist.
• references/components.md -- component catalog
• references/canonical-imports.md -- "which import wins?" decision tree (covers the Card / Tooltip / Modal / Hero look-alike landmines)
• references/tokens.md -- Tailwind v4 token architecture, custom utilities, dark mode, arbitrary-value priority
• references/spacing-typography.md -- heading sizes, spacing scale, breakpoints
• references/gotchas.md -- confusion patterns and stale shadcn token names
• references/variant-vs-new.md -- three-tier reuse hierarchy + backward-compatible refactor pattern
• references/cleanup-playbook.md -- anti-pattern -> canonical pattern map
• references/i18n-rtl.md -- RTL, locale-aware formatters, BiDi handling
• references/server-vs-client.md -- SSR boundary patterns
• references/a11y.md -- project-specific accessibility notes
• references/card-walkthrough.md / page-hero-walkthrough.md -- end-to-end worked examples
• references/new-component-checklist.md -- pre-merge checklist for new UI primitives
• AGENTS.md -- updated styling-conventions section (tv preferred for new/refactored work) and added a pointer to the skill
• docs/ds-implementation.md -- stubbed; redirects to the skill + Storybook (preserves the URL for stale links)

~3000 lines across 14 skill files. SKILL.md itself is 126 lines (well under the spec's 500-line guidance).

Out of scope (intentional)

• No code changes to existing components. Tracked work for follow-up PRs.
• No bulk cva -> tv migration. tv is preferred for new and refactored work; opportunistic swaps are fine when you're already touching a component.
• No Heading primitive, no --text-page-title token. These are gaps the audit surfaced; tracked for design discussion.
• No new Storybook stories. Tracked as a separate issue.

Follow-ups (will be posted as issues after merge)

• Cleanup tracking issue -- single tracking issue with ~50 checkbox items applying the cleanup-playbook.md to existing code (raw <a>/<button> replacements, hex literal tokenization, RTL fixes in ui/select.tsx and ui/dropdown-menu.tsx, Drawer removal, *SSR rename after consolidation, etc.).
• Storybook stories issue -- stories for the canonical primitives, grouped by category (overlay / form / display / navigation) for review-able PRs.
• Skill maintenance process -- a docs/maintaining-skills.md doc, a PR-template line ("did this PR touch UI? check the skill"), and a CI check that flags new ui/ components missing from the catalog. Tracked in the cleanup issue. Reviewers, please weigh in here -- the maintenance approach is open to input.

Test plan

• AGENTS.md / CLAUDE.md changes render correctly and the skill pointer resolves
• docs/ds-implementation.md stub resolves and links to the skill
• Skill files are valid markdown (no broken cross-references)
• SKILL.md frontmatter validates against the agentskills.io spec
• Post-merge: run a representative "build a new card-grid section" task with the skill loaded vs. without -- compare outputs, refine the skill based on what it adds vs. what's noise

The skill itself adds no executable code, so no test suite changes are required.

[netlify]

✅ Deploy Preview for ethereumorg ready!

Name	Link
🔨 Latest commit	deca48a
🔍 Latest deploy log	https://app.netlify.com/projects/ethereumorg/deploys/6a0365029e94830008ab2944
😎 Deploy Preview	https://deploy-preview-18120.ethereum.it
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	7 paths audited Performance: 73 (🟢 up 8 from production) Accessibility: 96 (no change from production) Best Practices: 100 (no change from production) SEO: 98 (🔴 down 1 from production) PWA: 59 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[myelinated-wackerow]

Manual validation

Quick sanity check before merge:

1. Triggers correctly -- "I need to add a card grid to the staking page. what card component should we use?" (asked from this PR branch) loaded the skill and produced a direct canonical answer: Card from @/components/ui/card, warned off the legacy @/components/Card import, recommended composing with Stack/Flex for the grid wrapper, surfaced the variant-over-new-component principle.
2. Provides a real delta vs no skill -- the same prompt from dev (skill not yet merged) got a more cautious response: Claude asked clarifying questions about card contents and which staking page before recommending. The skill saves a round-trip on canonical-choice questions.
3. Doesn't over-trigger -- "duplicate keys in src/intl/en/page-staking.json, how should I resolve this?" correctly did NOT trigger the skill (that's intl JSON maintenance, not UI work).

We also tried the skill-creator description-optimization loop for quantified scores, but it hit a tooling issue: the claude -p test harness couldn't load the skill, giving a 0% trigger rate across all queries / 4 iterations regardless of description changes. That's a separate skill-discovery problem in subprocess invocations, unrelated to this skill's content. Worth tracking but doesn't block merge.

Ready to land based on qualitative signal. Real-world usage will surface anything missed.

[pettinarip]

🚀