design-language
Skill9 starsChanged 18 days agoApache-2.0View on GitHub
ShipIt design language: color tokens, typography, iconography, motion, and multi-theme architecture. Load when working on UI components, styling, theming, or adding new visual elements.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- joi-fairshare/agentic-workflowtheir own version, first seen Nov 14, 2026
- crsmithdev/alephtheir own version, first seen Nov 8, 2026
- jthorare/agentic-workflowtheir own version, first seen Oct 25, 2026
- mhylle/claude-skills-collectiontheir own version, first seen Oct 9, 2026
- Xoshbin/asyartheir own version, first seen Oct 9, 2026
- ara-mkr/claude-artisantheir own version, first seen Jul 27, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- Xoshbin/asyar★ 986same name
- ara-mkr/claude-artisan★ 72same name
- mhylle/claude-skills-collection★ 20same name
- joi-fairshare/agentic-workflow★ 3same name
- jthorare/agentic-workflow★ 3same name
- codywilliamson/shipwright★ 0same name
- crsmithdev/aleph★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-endpointSkill
- android-buildSkill
- client-architectureSkill
- deployment-architectureSkill
- docs-navigatorSkill
- dogfooding-shipitSkill
- frontend-design:frontend-designSkill
- git-architectureSkill
- prompt-architectureSkill
- server-architectureSkill
- session-containersSkill
- session-lifecycleSkill
- session-processesSkill
- testing-and-qualitySkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
Never use raw Tailwind color classes like bg-gray-950 or text-blue-500 in components — use bg-[var(--color-bg-primary)].
- Very specific: line 79
Sizes: Use ICON_SIZE constants from src/client/design-tokens.ts — SM (16px) inline with text, MD (20px) buttons/nav, LG (32px) empty …
- Distinctive: line 157
Add it to the table above in this skill
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Design Language
ShipIt uses semantic design tokens (CSS custom properties) for all colors. Themes are token overrides applied via a class on <html>. All UI code references tokens — never raw Tailwind color classes.
Concrete color values live in per-theme CSS files under src/client/themes/. Each file defines one theme's token values. src/client/index.css imports them and contains shared rules (animations, scrollbars, syntax highlighting). Theme state is managed by useTheme() in src/client/hooks/useTheme.ts (persisted to localStorage key shipit-theme).
src/client/themes/
light.css ← :root { --color-bg-primary: ...; }
dark.css ← .dark { --color-bg-primary: ...; }To add a new theme: create a new CSS file in themes/, import it in index.css, register the name in useTheme(). No component changes needed.
Color Tokens
Never use raw Tailwind color classes like bg-gray-950 or text-blue-500 in components — use bg-[var(--color-bg-primary)].
| Token | Purpose |
--color-bg-primary | Page/app background |
--color-bg-secondary | Sidebar, secondary panels |
--color-bg-tertiary | Cards, inputs, code blocks |
--color-bg-elevated | Dropdowns, modals, popovers |
--color-bg-overlay | Backdrop behind modals |
--color-bg-hover | Hover state for interactive surfaces |
--color-bg-active | Active/pressed state |
--color-text-primary | Body text, headings |
--color-text-secondary | Descriptions, timestamps |
--color-text-tertiary | Placeholders, disabled |
--color-text-inverse | Text on filled backgrounds |
--color-text-link | Clickable text links |
--color-border-primary | Panel borders, dividers |
--color-border-secondary | Input borders |
--color-border-focus | Focused input ring |
--color-accent | Primary buttons, active tabs |
--color-accent-hover | Primary button hover |
--color-accent-text | Text on accent backgrounds |
--color-accent-subtle | Tinted backgrounds, badges |
--color-success | Connected, passed, deployed |
--color-success-subtle | Success background |
--color-error | Failed, disconnected, destructive |
--color-error-subtle | Error background |
--color-warning | In-progress, caution |
--color-warning-subtle | Warning background |
--color-info | Informational, typing |
--color-info-subtle | Info background |
--color-pr | PR open/merged indicator |
--color-folder | Folder icon in file tree |
--color-autofix | Auto-fix toggle/indicator |
--color-context-ok | Context meter 0–60% |
--color-context-mid | Context meter 60–80% |
--color-context-high | Context meter 80–90% |
--color-context-full | Context meter 90%+ |
--color-scrollbar-thumb | Scrollbar thumb |
--color-scrollbar-thumb-hover | Scrollbar thumb on hover |
--font-size-code | Monospace / code block font size |
--duration-fast | Color transitions, exits |
--duration-normal | Enter animations, layout shifts |
--duration-slow | Loading spinners |
--ease-default | Default easing |
--ease-out | Enter animations |
--ease-in | Exit animations |
Typography
System font stack, no custom web fonts. Body: text-sm, headings: text-lg font-semibold, code: font-mono text-[var(--font-size-code)], small: text-xs.
Iconography — Phosphor Icons
Library: @phosphor-icons/react. All icons use Phosphor — no inline SVGs or Unicode characters.
Sizes: Use ICON_SIZE constants from src/client/design-tokens.ts — SM (16px) inline with text, MD (20px) buttons/nav, LG (32px) empty states, XL (48px) hero.
Weights: "regular" (default), "bold" for emphasis, "fill" for toggle-on states, "duotone" sparingly for illustrations.
The one exception — a scene, not a symbol. A hand-written inline <svg> is allowed only for a bespoke illustration in an empty or onboarding state, where the drawing has to depict a relationship a glyph set cannot: an arrangement of parts (a slot, a container, an arrow between two things), a state (empty, waiting, filled), or a data-driven shape. Composed Phosphor glyphs are the default even for illustrations — reach for this only after trying them. Anything that labels an action, a status, or a row is an icon, and icons are always Phosphor, no exceptions.
An illustration under this exception must still: use only semantic colour tokens (it is drawn in every theme); carry aria-hidden="true" unless it conveys something the adjacent copy does not; scale with its container (max-w-full h-auto, never a fixed width in a resizable pane); and disable any animation under prefers-reduced-motion. Current members of this set: PreviewFrame/PreviewSetupInvite.tsx (empty-preview scene), RocketLaunch.tsx (new-session animation), ContextDial.tsx (data-driven gauge).
The other exception — a mark you quote, not one you draw. A vendor logo is an inline <svg> too, because Phosphor is a set of generic UI symbols and ships no brand marks. Nothing about a logo is a design decision: the shape belongs to its owner, so it is copied verbatim (Simple Icons is CC0 and is where ours come from) rather than approximated with a glyph. A logo must carry aria-hidden="true" — the vendor's name is invariably beside it, and a mark that announces itself makes a screen reader say the name twice.
Colour is the one judgement left, and it is decided by the brand, not by taste. A mark the vendor publishes in black (Anthropic, OpenAI, Vercel, Z.ai) is drawn in currentColor, because a hardcoded #000 disappears on a dark background — this is not a compromise, it is what the mark looks like in each theme. A brand whose colour IS the mark keeps it as a literal hex, checked for legibility on light and dark: Settings/components/LinearCredential.tsx's LinearLogo (#5e6ad2) is the standing example. And where a set of marks is drawn as a column, keep the set consistent rather than colouring one row of it — ServiceLogo.tsx draws all six service marks in currentColor for that reason, since only DeepSeek's is coloured and one blue tile among five grey ones reads as a rendering bug.
This exception is for logos only — it does not license a hand-drawn icon for anything ShipIt owns.
Color: Icons inherit currentColor. Set via parent's text color token:
import { ICON_SIZE } from "../design-tokens.js";
<span className="text-[var(--color-text-secondary)]">
<GitBranch size={ICON_SIZE.SM} />
</span>Key mappings (non-obvious or domain-specific):
| Concept | Icon | Color Token |
| PR open | GitPullRequest | --color-pr |
| PR merged | GitMerge | --color-pr |
| PR closed | GitPullRequest | --color-text-tertiary |
| Success | CheckCircle | --color-success |
| Error | XCircle | --color-error |
| Warning | Warning | --color-warning |
| Pending | CircleNotch | With animate-spin |
| Folder | Folder / FolderOpen | --color-folder |
| Deploy | Rocket | |
| Trash | Trash | --color-error (destructive) |
| External link | ArrowSquareOut |
Motion
Motion tokens are defined in index.css (shared, not per-theme). Use transition-[color] duration-[var(--duration-fast)] instead of Tailwind's transition-colors to reference the token. Avoid animating layout properties (width, height) unless explicitly resizing.
Do not animate a surface full of text on entry — neither a scale nor a fade. Both move the text of a large panel, in different ways. A scale moves it geometrically: the fade lands first, so the text is readable while the scale still has ~1% to run and every line slides a pixel or two into place. A fade moves it optically: mid-opacity the element is composited on its own layer, where glyphs are antialiased in grayscale, and on the final frame the layer collapses and they re-render with subpixel antialiasing — the geometry never changes, but the eye reads the change in glyph weight as a settle. DialogContent therefore has no entrance animation at all; the overlay's fade carries it. dialog.test.tsx guards this. Small surfaces (tooltip, popover, dropdown menu) keep both effects — near their transform origin, holding a line or two, neither is legible.
UI Primitives
Shared components in src/client/components/ui/ using CVA (class-variance-authority) for variant-based styling. Never duplicate token class strings across components — use these primitives instead.
| Component | File | Variants |
Button | button.tsx | variant: primary, secondary, destructive, ghost. size: sm, md, lg |
Badge | badge.tsx | variant: default, success, error, warning, info |
StatusDot | status-dot.tsx | status: success, error, warning, info |
Banner | banner.tsx | variant: error, warning, info, success |
Dialog | dialog.tsx | Modal overlay with backdrop |
Tooltip / Popover / DropdownMenu / OverflowMenu | tooltip.tsx, popover.tsx, dropdown-menu.tsx, overflow-menu.tsx | Floating surfaces |
Tabs / Tab | tabs.tsx, tab.tsx | Tab strips |
Avatar, CopyButton | avatar.tsx, copy-button.tsx | — |
ls src/client/components/ui/ is authoritative if this table lags.
Example usage:
import { Button } from "./ui/button.js";
<Button variant="destructive" size="sm">Delete</Button>Adding a new primitive
- Create
src/client/components/ui/<name>.tsx - Define variants with
cva()— use only design tokens for colors, motion tokens for transitions - Accept
classNameprop and merge it with CVA output (so consumers can add layout classes like margins) - Forward
refand spread remaining props onto the root element - Export the component and its variant props type
- Add it to the table above in this skill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

