Skip to main content
skill CX Codex

design-system · daveebbelaar — Claude Code skill for macOS design systems

The design-system Claude Code skill organizes a macOS app’s accent color and design tokens. It activates for requests about themes, shared screen styles, or a style guide.

MIT 1,000 installs ★ 1,933 updated 2026-11-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daveebbelaar/bama --skill design-system -a claude-code
Open on GitHub

What design-system does

The skill helps define an accent color and a design system for a macOS app. It uses Swift tokens for shared values and puts guidance on when to use them in design/DESIGN-SYSTEM.md, covering areas such as colors, spacing, corner radii, and motion.

For an existing app, it recommends reviewing the screens, collecting hard-coded values, then replacing them with tokens one screen per commit. Build the app and capture a snapshot after each change. The accent comes from docs/BRIEF.md; when that brief names no color, the app keeps the Mac’s system accent.

The example uses Theme.swift, AppearanceSettings.swift, and other Swift files under Sources/<App>/UI/. It also sets rules for contrast, Reduce Motion, and native controls. Installation through Claude Code uses npx.

What it helps with

  • define shared color and interface tokens for a macOS app
  • replace hard-coded values screen by screen
  • document when each token belongs in design/DESIGN-SYSTEM.md
  • align animation rules with Reduce Motion across screens

Example prompts for the agent

  • Set up a design system for this macOS app.
  • Create shared tokens and document their use in design/DESIGN-SYSTEM.md.
  • Add an accent-color choice to the app’s settings.

How to install design-system

1Skills CLI (Vercel)

npx skills add daveebbelaar/bama --skill design-system -a claude-code

2Manually: put the files in place

~/.claude/skills/design-system/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/design-system/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about design-system

How do I install design-system in Claude Code?

Run npx skills add daveebbelaar/bama --skill design-system -a claude-code. The skill file is installed at ~/.claude/skills/design-system/SKILL.md.

What does design-system do?

It helps define an accent color and a design system for a macOS app, using Swift tokens for shared values and design/DESIGN-SYSTEM.md for their usage rules.

How does the skill choose the app’s accent color?

It starts with the Look section in docs/BRIEF.md. If no color is named, it keeps the Mac’s system accent, while leaving the color picker available in settings.

Source text

SKILL.md · MIT
---
name: design-system
description: Accent color and design system for a macOS app, from the app's accent and the accent picker in Settings to Swift tokens in code plus a design/DESIGN-SYSTEM.md that says which token to use when. Use when the user wants a brand or accent color, wants people to pick a color, when an app has more than a few screens, when screens drift apart or animations feel inconsistent, or when the user asks for themes, a style guide, or design tokens.
---

# Design system

A design system is a short list of **tokens** in code and one page that
says which token to use when. Every screen uses tokens, never raw values.
Then a change in one place changes the whole app, and an agent can review a
screen against one page.

Start from `mac-design`. Tokens cover only what the system does not:
the accent, custom surfaces, radii, motion, overlays, and custom controls.

The app keeps Apple's look. Only the accent color changes. For parts of
your own (a custom sidebar, buttons, icons), call the Skill tool with
`design-kit`. To copy the look of an app the user names, call it with
`design-from-app`.

The template already has the base in `Sources/<App>/UI/`:

- `Theme.swift`: the accent colors (`Theme.all`), the saved choice
  (`ThemeStore`), the tokens `Palette.accent`, `Palette.accentText`,
  `Palette.onAccent`, and `.themed()`, which tints every scene.
- `AppearanceSettings.swift`: Settings > Appearance, where people pick the
  accent. Light and dark mode follow the Mac. Apple advises against an
  app-specific mode setting; add a System/Light/Dark picker only when the
  owner asks for one, with System as the default. [HIG Dark Mode]
- `Grid.swift`: spacing (see the `layout-grid` skill).

## 1. Pick the accent

Read `## Look` in `docs/BRIEF.md`. With no color named, keep `system`: it
follows the accent color the person set for their Mac.

For a brand color, set `ThemeStore.brand` to a `Theme` with three shades:
`light` (accent text in dark mode), `base` (fills and tint), and `deep`
(accent text in light mode). Set `darkText: true` when white text on
`base` is hard to read (yellow, mint, cyan). Keep
`ThemeStore.defaultID = "system"`. The brand then shows only while the
Mac's accent is Multicolor, as in Apple's apps. Any other accent the person
chose for their Mac wins, and so do sidebar icons, which people expect in
their own accent. [HIG Color, Sidebars]

Use brand color sparingly: the app icon, an empty state, one hero element
in the content. Keep it off most controls. [HIG Branding]

To compare colors, take snapshots with `APP_ACCENT=<id>` for two or three
of them and show the user the PNGs. Keep the picker in Settings, so people
can still choose their own color.

Check: `ThemeStore.defaultID` is "system", and the snapshots show the
accent on buttons, toggles, and selection in light and dark mode.

## 2. Collect

New app with no views yet? Skip this step: write the token files with the
defaults below before the first view.

Existing app: read every view. List each raw value you find: hex colors, opacities,
corner radii, paddings, frame widths, animation durations and curves,
custom button styles. Group them. Most apps have 3 to 5 of each where 1 or
2 are meant.

## 3. Write the tokens

Accent values live in `Theme.swift`. The rest get one file per group in
`Sources/<App>/UI/`. Add each token when the app first needs it:

| File | Holds |
| --- | --- |
| `Theme.swift` | the accents, `ThemeStore`, `.themed()`, and `Palette`: `accent`, `onAccent` (text and symbols on accent fills), `accentText` (accent-colored text: deep shade in light mode, light shade in dark mode) |
| `Grid.swift` | the spacing scale (`Space`) and the layout probes |
| `Surfaces.swift` | `surface`, `surfaceHover`, `hairline`, one warning color |
| `Radius.swift` | `xs 6` chips and key caps, `sm 8` controls, `row 10` row hover fills, `md 12` cards, `lg 18` widgets, `xl 26` floating glass |
| `Layout.swift` | `contentWidth`, fixed column and sheet widths |
| `Motion.swift` | `hover`, `quick` (presses, small flips), `ui`, `select` (selection moving through a live list), `appear`, `dismiss`, `glide`, `numberRoll`, `listChange`, loops (`pulse`) that stop under Reduce Motion |
| `Components.swift` | more control styles: `HoverButtonStyle`, `.hoverFill`, toggles, chips |
| `Overlay.swift` | one panel builder, one entrance, one exit |

Surfaces adapt to light and dark. Views read the accent through `.tint` or
`Palette`, so a new choice in Settings redraws the whole app.

## 4. Write design/DESIGN-SYSTEM.md

One section per file above. Each section says which token to use when, and
the rules that go with it. Keep it under 100 lines. Rules that transfer to
most apps:

- Never hard-code a hex accent. Use `.tint` or `Palette.accent`.
- Every custom color has four values: light, dark, and a stronger one of
  each for Increase Contrast (`Color(light:dark:highContrastLight:highContrastDark:)`
  in `Theme.swift`). [HIG Color]
- Never redefine or copy a semantic color (`.separator` as text, a label
  color as a fill). Their values change per release.
- A custom surface in its neutral state is a little translucent, so it
  picks up the desktop tint like system surfaces. A colored state is
  opaque.
- A custom font only for headings. Body and captions stay in the system
  font, and every custom font has a bold weight for the Bold Text setting.
- Accent-colored text uses `Palette.accentText`. Text on an accent fill
  uses `Palette.onAccent`, never a fixed white.
- Style controls with `ButtonStyle` and `ToggleStyle`. Never rebuild a
  control from shapes: it loses the keyboard, focus, and VoiceOver.
- Inner corners are concentric: inner radius = outer radius - inset.
- Every animation goes through `Motion`, so a per-feature "Full, Fast,
  Off" setting and Reduce Motion apply everywhere.
- Search results and switchers do not animate. Speed wins.
- Hover never moves a selection. Only a click or a key does.
- Units ("KB/s", "%") never animate. Only the number does
  (`.contentTransition(.numericText())`).
- Never animate a view's first layout. Overlays wait one frame, then
  animate opacity, scale, and a few points of travel.
- Leave room around glass for its shadow (about 3 times the shadow radius).
- One primary button per page or card.

## 5. Migrate

Replace raw values screen by screen, one commit per screen. After each,
build and snapshot (`build-and-verify` skill). The screen looks the same or
better, never worse.

## 6. Point agents at it

Add one line to the app's `CLAUDE.md` (create the file if it is missing):
"Design rules: `design/DESIGN-SYSTEM.md`. Use its tokens; never raw colors,
radii, or durations."

Done when this finds no hits outside the token files:

```bash
grep -rnE 'cornerRadius: [0-9]{1,2}\b|duration: [0-9]|\.spring\(response|\.snappy\b|\.easeInOut|\.easeOut\(|Color\(hex:|Color\(red:' Sources/ \
  | grep -v 'Path(roundedRect'
```

(hex strings in data and comments are fine), and DESIGN-SYSTEM.md has a section
for every token file.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Design →

design-system by other authors comes first.

design-system claudekit The design-system skill builds design tokens, component specs, and presentation slides. Use it when an interface and its slides need to follow one visual system. CX Codex +1 54,500installs design-system affaan-m Builds a design system out of the styles already in your repo, or audits them: tokens, a ten-point UI score, and a check for generic AI styling. CX Codex +1 6,800installs design-system official anthropics A skill for Claude Code, Cursor, Codex, and three other platforms that audits design systems for inconsistencies, generates component docs, and drafts new patterns. Triggered with /design-system audit, document, or extend. CX Codex +1 4,700installs design-system Donchitos design-system walks one game system through every required GDD section and cross-references its dependencies. Useful when a design doc grows faster than you can keep it straight. CX Codex +1 731installs design-system jezweb Reads a live site, HTML file, or screenshot and turns it into a semantic design system in DESIGN.md. Use it when a new project has to match an existing visual language. CX Codex +1 1,200installs extract-design-system arvindrk The extract-design-system skill extracts design primitives from a public website and generates starter tokens.json and tokens.css files for your project. CX Codex +1 131,800installs tailwind-design-system Seth Hobson tailwind-design-system helps build design systems with Tailwind CSS v4, from theme tokens to component variants. Use it when a project needs shared UI patterns. CX Codex +1 70,180installs expo-design-system expo expo-design-system is a Claude Code skill that organizes design tokens and reusable components in Expo apps and audits styles to eliminate inconsistencies. CX Codex +1 22,700installs design-system-patterns Seth Hobson The design-system-patterns skill for Claude Code covers token architecture, theming, and component patterns. It activates for token creation, theme switching, and component-library foundations. CX Codex +1 15,953installs stitch::manage-design-system official google-labs-code stitch::manage-design-system is a Claude Code skill that builds design systems in Stitch and applies them to screens. It runs when a project needs design tokens created or updated. CX Codex +1 11,900installs figma-create-design-system-rules official openai figma-create-design-system-rules — a skill for Claude Code, Codex, Cursor and other agents that generates project-specific design system rules by reading your codebase. CX Codex +1 3,200installs

From the same set21

The whole set →
layout-grid layout-grid is a Claude Code skill that enforces grid and alignment rules in macOS SwiftUI apps. It runs when building custom UI components or after layout changes. CX Codex +1 1,000installs user-stories Turns app briefs, research, or screen indexes into prioritized user stories with checkable acceptance criteria. It runs after app-brief or clone, or when asked to plan features and choose what to build first. CX Codex +1 1,000installs swift-swiftui The swift-swiftui Claude Code skill sets Swift 6 and SwiftUI practices for macOS apps. It activates while writing, reviewing, or debugging Swift code, including concurrency and Sendable errors. CX Codex +1 1,000installs design-kit design-kit — a skill for Claude Code and Cursor builds a custom macOS SwiftUI design system with tokens and components. Runs when you need a brand look or custom controls. CX Codex +1 1,000installs new-mac-app new-mac-app is a Claude Code skill that scaffolds a native SwiftUI macOS app from a working template. It starts when a new Mac app or project skeleton is requested. CX Codex +1 1,000installs test-mac-app The test-mac-app Claude Code skill lays out a testing flow for macOS apps, from Swift tests to controlling a running app. It activates when adding logic, fixing bugs, or checking a release. CX Codex +1 1,000installs ux-design The ux-design skill for Claude Code runs a UX pass for a macOS app feature before coding, covering terminology, flows, surface selection, and accessibility. Runs before coding a story that adds a screen, an action, or text. CX Codex +1 1,000installs bama The bama skill for Claude Code picks the next step in building a native macOS app. It routes work from an initial idea through research, implementation, and verification. CX Codex +1 1,000installs

Project sponsors

Companies that keep this analytics open