Swiftner Design Skill

A Claude Code skill that teaches Claude to write, refactor, and review Swiftner UI consistently across the three surfaces:

• HUD frontend — swiftner-hud/frontend/ (React + Chakra v2)
• HUD browser extension — swiftner-hud/browser-extension/ (Plasmo + Chakra v2)
• Marketing website — website/ (Laravel + Statamic + Inertia + React + Tailwind v4)

The skill points Claude at the right Figma theme for each surface and at the existing semantic aliases in code, so generated UI follows the design system without hand-waving.

Goal: a Swiftner style guide that keeps developers on the straight and narrow and gives them the tools to build new functionality and surfaces quickly — on-system, with usability above all.

What is in here

• SKILL.md — entry point Claude reads first: core principles, a quick-reference index, the code-review checklist, and working notes.
• references/ — progressive-disclosure files Claude reads when a specific topic comes up:
  • 00-routing.md — how to detect which surface you are on.
  • 10-tokens-chakra.md — HUD palette, semantic aliases, component variants.
  • 11-tokens-tailwind.md — website palette, utility classes, fonts.
  • 20-density.md — spacing & density per surface.
  • 40-typography.md — Themes model, semantic intent → tokens.
  • 50-review.md — accessibility + visual review (the in-skill rams pass) to run when frontend work is done.
  • 60-coaching-patterns.md — coaching / AI / score-board UI patterns (HUD).
  • 70-craft.md — craft & polish: usability, depth, motion, and the faithful-but-not-generic bar.
  • 80-voice.md — voice & UI copy: labels, microcopy, and headlines in Swiftner's voice.

An anti-patterns reference + an automated audit script are planned but deferred until the in-progress website redesign lands, since they target the website's raw-hex cleanup.

Installing locally for testing

Clone this repo somewhere on your machine, then symlink (or copy) into your Claude Code skills directory:

# Pick a stable location
cd ~/src
git clone https://github.com/Swiftner/design-skill.git

# Symlink into Claude Code (adjust path to where your skills live)
ln -s ~/src/design-skill \
  ~/.claude/skills/swiftner-design

Restart Claude Code. The skill should appear in available_skills as swiftner-design.

The installed directory must be named swiftner-design (matching the name: in SKILL.md) — as the symlink above does. The repo folder is design-skill, so do not install it under that name.

Conventions

• Engelsk i SKILL-filer. Bedre triggering, og koden er på engelsk uansett.
• Norsk i issue-diskusjon og PR-er. Internt språk.
• Each references/*.md should be under ~500 lines. If it grows past that, split it.

How to make changes

1. Branch from main: git checkout -b your-change.
2. Edit the relevant file(s).
3. Run a quick sanity-check by asking Claude to perform a representative task in a Swiftner repo with the skill active.
4. Open a PR. Mia approves and merges.

Source design system

The canonical Figma file: Swiftner Design System 2.0 (file key NbVO1jO4ODSxk8neXgtN0E).

Figma reality: the file's top-level pages are 1. HUD Dashboard, 2. HUD Extension, Design system, and **archived. The website is not a top-level page, but it has a live Website variable mode (var set 29-1470) under node 65:1838 (app.css + tailwind/colors-from-figma.js are the handier code reference). When the skill says get_variable_defs, the exact MCP tool name depends on install: mcp__figma__get_variable_defs (CLI-added server) or mcp__plugin_figma_figma__get_variable_defs (plugin). Query a concrete leaf node (a page/frame id errors; an empty leaf returns {}). Probes: HUD 53:2575, Website 1757:10470.