Skip to main content
skill CX Codex

design-kit — Claude Code skill: what it does, how to install

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.

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-kit -a claude-code
Open on GitHub

What design-kit does

The skill creates a custom macOS SwiftUI design system using three token layers, custom typography, icons, and native controls. The agent writes a spec in design/KIT.md, manages tokens in DesignKit/Tokens.swift, and sets up a component gallery.

All UI parts live in Sources/<App>/DesignKit/. The workflow includes style checks via shell scripts and a gallery mode enabled by APP_KIT_GALLERY=1 to review states before screen integration.

What it helps with

  • write a design system spec for a SwiftUI app
  • organize design tokens into three layers
  • build custom UI components with all states
  • set up a component gallery for visual testing

Example prompts for the agent

  • Create a custom design system for the SwiftUI app
  • Set up tokens and components in the design kit
  • Build the component gallery to test UI states

How to install design-kit

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

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

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

Questions about design-kit

How to install design-kit in Claude Code?

Run npx skills add daveebbelaar/bama --skill design-kit -a claude-code in your terminal, then reference ~/.claude/skills/design-kit/SKILL.md.

What does design-kit do?

It builds a custom macOS SwiftUI design system covering color tokens, type roles, icon sets, and component states.

What is needed to use design-kit?

A macOS SwiftUI project and an AI coding assistant supporting skills.

Source text

SKILL.md · MIT
---
name: design-kit
description: Custom design system for a macOS SwiftUI app with its own parts, not Apple's, covering three token layers, type, an icon set, every part in every state, custom window chrome, a parts gallery, and checks. Use when the user wants the app to have its own look and feel, a brand, or custom buttons, rows, and sidebars, when design-from-app has measured a reference app, or when the user asks for a design system or component library.
---

# Design kit

A native look comes from Apple's parts. A custom look comes from your own
parts: your sidebar row, your button, your checkbox, your icons. SwiftUI
draws all of them. A kit is those parts, the numbers behind them, and one
page that shows every part in every state.

Most apps keep Apple's parts and only pick an accent color (`design-system`
skill). Build a kit when the parts themselves must change. To copy the look of an existing app,
call the Skill tool with `design-from-app` first: it measures the app and
then comes back here.

Everything lives in `Sources/<App>/DesignKit/`. Code for every step:
[parts.md](parts.md).

## 1. Write the spec

Write `design/KIT.md` from [kit-spec.md](kit-spec.md): three words for the
feel, the tokens, the type scale, the icon rules, and one section per part
with its sizes and states. Agents build from this page and review against it.

Check: every part the app's screens need has a section with its sizes and
its states.

## 2. Tokens in three layers

`DesignKit/Tokens.swift`:

1. **Palette**: raw colors, named by hue and step (`gray50`, `blue600`).
   Only this file reads it.
2. **Meaning**: `Ink.text`, `Ink.accent`, `Ink.selection`, `Ink.divider`,
   with a light and a dark value each. Parts read only this layer.
3. **Scales**: `KitType` (type roles), `Metric` (sizes), `Motion`
   (named intents like `hover` and `check`).

A rebrand changes the palette. A dark mode fix changes the meaning layer.
Neither touches a part.

Check: `grep -rn 'Palette\.' Sources/ | grep -v Tokens.swift` finds nothing.

## 3. Type

Name styles by role (`title`, `body`, `label`, `section`, `meta`), never
by size. Use the system font unless the brand needs its own; a bundled
font goes in `Resources/Fonts/` with `ATSApplicationFontsPath` in
`Info.plist.in`. Half-point sizes are fine when a reference needs them.

Check: views set fonts only through `.kitType(...)`.

## 4. Icons

Icons decide the feel more than color does. Views name a `KitIcon`, never
an SF Symbol or a file, so the whole set can change in one place.

- Start from SF Symbols at a fixed size and weight. Light weights read
  less like Apple.
- For a set of your own, draw each icon as a SwiftUI `Shape` from its SVG
  path, or make custom symbols in the SF Symbols app.
- One size, one stroke weight, one corner style for the whole set.
- A selected row may switch to the filled form.

Check: `grep -rn 'systemName:' Sources/ | grep -v DesignKit/` finds nothing.

## 5. Parts

One file per family in `DesignKit/Components/`: sidebar, rows, buttons,
fields, menus. Each part:

- Is a real control. Style a `Button` with a `ButtonStyle`, a `Toggle`
  with a `ToggleStyle`, a field with a `TextFieldStyle`. Never a shape with
  a tap gesture: it loses the keyboard, focus, and VoiceOver.
- Has every state: rest, hover, pressed, selected, focused, disabled, in
  light and dark. Hover uses `onHover`, pressed uses
  `configuration.isPressed`, disabled reads `isEnabled`.
- Takes a forced state for the gallery, so hover and pressed show up in a
  snapshot.
- Reads only meaning tokens, `KitType`, `Metric`, `Motion`, and `KitIcon`.

Check: the part matches its section in `design/KIT.md` in every state.

## 6. Window chrome

For a fully custom look, hide the title bar and draw your own top bar,
and build the sidebar from kit rows instead of `List`. Keep the traffic
lights, menus, context menus, sheets, and alerts native: users depend on
them. SwiftUI cannot move the traffic lights; a small `NSViewRepresentable`
reaches the `NSWindow` (parts.md, Window chrome).

A custom sidebar matches the macOS 27 system one where people would
notice: the selected row's text turns semibold, the selection fill dims
when the window is inactive (`@Environment(\.appearsActive)`), and row
corners stay concentric with the sidebar (mac-design patterns.md, "Custom
chrome that follows the window"). Custom glass bounces on click only on
controls.

Check: the window opens at its default size, the traffic lights sit where
the spec says, the custom sidebar moves with the arrow keys, and its
selection dims when another window is in front.

## 7. Gallery

`DesignKit/KitGallery.swift` shows every part in every state, in light and
dark, the way a storybook does. The app shows it instead of its pages when
`APP_KIT_GALLERY=1` is set, so the normal snapshot command captures it.
Review a new part here before it goes into a screen.

Check: the gallery snapshot shows every part from `design/KIT.md`, and the
user has seen it.

## 8. Checks

```bash
tools/grid-lint.sh
grep -rnE 'Color\(hex|Color\(red|\.font\(\.system|systemName:' Sources/ | grep -v DesignKit/
```

Both come back clean. Then build, snapshot, and run the `layout-grid`
checks on the screens (`build-and-verify` skill).

Done when `design/KIT.md` covers every part, every part is a real control
with every state, the gallery shows them all in light and dark, and the
checks above come back clean.

© daveebbelaar · MIT · daveebbelaar/bama

Similar skills

All skills for Design →

From the same set21

The whole set →
os-integrations The os-integrations Claude Code skill maps macOS APIs to system-level features and their required permissions. It applies when adding global shortcuts, screen capture, or controls for other apps’ windows. CX Codex +1 1,000installs 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-system 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. 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

Project sponsors

Companies that keep this analytics open