Claude-skill-registry-data maintaining-design-system

Design system maintenance for the site. Consult when modifying colours, typography, spacing, or themes. Covers token architecture, theme synchronisation, and CSS layers.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry-data

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry-data "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/maintaining-design-system" ~/.claude/skills/majiayu000-claude-skill-registry-data-maintaining-design-system && rm -rf "$T"

manifest: data/maintaining-design-system/SKILL.md

source content

Maintaining the Design System

Design system maintenance for the site. Tokens, themes, typography, and CSS architecture.

British English throughout—code, comments, documentation, content.

When to Use

Consult this skill when modifying design tokens, adding or updating themes, or changing typography scales. Reference SHIKI.md for syntax highlighting changes. Reference COMPONENT_DESIGN.md when creating new components or establishing component patterns.

Philosophy

The design system pays homage to Swiss Style—clean, grid-locked, typographically precise. Every spatial decision aligns to an 8px grid. This constraint breeds coherence.

Discipline over necessity. The project's scale doesn't demand this rigour; the practice itself is valuable. The source will be public—it should exemplify high-quality design decisions.

Token Architecture

Design tokens live in

src/styles/tokens/

. Each file defines a category of CSS custom properties.

File	Purpose
`colours.css`	Theme colour definitions (semantic: `--bg` , `--fg` , `--muted` , `--rule` , `--highlight` , `--emphasis` )
`typography.css`	Font families, size scale, line heights, letter spacing
`spacing.css`	Margin/padding scale (8px base)
`sizing.css`	Fixed dimensions
`layout.css`	Safe area insets for mobile
`z-index.css`	Stacking context scale
`transitions.css`	Animation timing tokens
`borders.css`	Border width scale
`index.css`	Barrel import (order matters: colours first)

Using Tokens

Before applying tokens, check the relevant file in

src/styles/tokens/

to verify available values and naming conventions. Token naming is not yet fully consistent across categories—some use pixel values, some use multipliers, some use semantic names. Don't assume a pattern; verify what exists.

The 8px Grid

All spacing, sizing, and line heights must resolve to multiples of 8px. When adding new tokens:

Convert target pixels to rem (divide by 16)
Verify the pixel value is divisible by 8
Follow the naming convention established in that token file

/* Values must align to 8px grid */
--example: 2rem;    /* 32px, divisible by 8 ✓ */
--example: 1.875rem; /* 30px, breaks grid ✗ */

CSS Layers

Layer order in

src/styles/global.css

@layer reset, tokens, base, components, utilities;

This cascade ensures:

reset — Browser normalisation
tokens — Design variables (no selectors, just definitions)
base — Element defaults
components — Scoped component styles
utilities — Atomic overrides (Tailwind)

Prose and Unlayering

src/styles/prose.css

customises rendered MDX content, extending

@tailwindcss/typography

. It deliberately uses no

@layer

directive, placing it outside the layer system entirely.

Why: Tailwind utilities have high specificity within their layer. Prose styles need to override both the typography plugin defaults and base styles without fighting

!important

or specificity hacks. Unlayered styles win over layered styles regardless of specificity, giving prose full control over article typography.

Theme System

Four themes: steel (default), purple, charcoal, teal. Theme class applied to

<html>

<html class="theme-steel">

Each theme defines six semantic colours using OKLCH colour space in

src/styles/tokens/colours.css

.theme-steel {
  --bg: oklch(...);
  --fg: oklch(...);
  --muted: oklch(...);
  --rule: oklch(...);
  --highlight: oklch(...);
  --emphasis: oklch(...);
}

Theme Synchronisation

Theme colours appear in multiple locations. When modifying any theme colour, update all affected files:

Location	Purpose	Format
`src/styles/tokens/colours.css`	Primary token definitions	OKLCH
`src/styles/components/shiki.css`	Syntax highlighting overrides	OKLCH
`src/lib/theme/palette.ts`	OG images, meta theme-color	Hex
`public/sf-[theme].ico`	Per-theme favicon	Binary
`public/rss/styles.xsl`	RSS feed styling (steel only)	Hex

The Boids animation reads

--rule

dynamically at runtime—no manual sync required.

Adding a Theme

Add theme ID to

THEME_ORDER

and label to

THEME_LABELS

src/config/themes.ts

Define colour tokens in
```
src/styles/tokens/colours.css
```
Define syntax tokens in
```
src/styles/components/shiki.css
```
(see SHIKI.md)
Add OKLCH values to
```
THEME_COLOURS
```
in
```
src/lib/theme/palette.ts
```
Create favicon at
```
public/sf-[theme].ico
```
(manual step—requires image editor or favicon generator)
Test across all page types (home, blog index, blog post, static pages)

Typography

Two systems handle typography: components for UI chrome, prose.css for rendered content.

Type Scale

Minor third ratio (1.2) with 8px-aligned line heights. Defined in

src/styles/tokens/typography.css

Typography Components

For UI elements—headers, navigation, metadata, labels. Located in

src/components/typography/

Component	Purpose	Default Colour
`Overline`	Uppercase labels, section headers	muted
`Caption`	Dates, metadata, supporting text	muted
`Body`	Taglines, descriptions	muted
`SheenText`	Interactive text with hover animation	fg

All accept

tag

color

, and spread attributes.

Prose Styling

For rendered MDX content—blog posts, long-form writing.

src/styles/prose.css

extends

@tailwindcss/typography

and targets elements within

.prose

Headings: size, weight, spacing, anchor link styling
Paragraphs: measure, spacing
Lists: marker styling, nesting
Code: inline and block treatment
Links: colour, hover states
Blockquotes: border, indentation

Modify prose.css when changing how blog content renders. Changes affect all existing posts.

Component Design

See COMPONENT_DESIGN.md for component structure, composability principles, spacing philosophy, and accessibility baseline.

Technological Constraints

Some libraries don't support CSS custom properties, requiring hardcoded values.

Satori (OG Images)

src/lib/og/

generates Open Graph images. Satori renders JSX to SVG but doesn't support CSS variables. Colours must be hex values, defined in

src/lib/theme/palette.ts

export const THEME_COLOURS: Record<Theme, ThemeColours> = {
  steel: {
    bg: oklchToHex(...),
    fg: oklchToHex(...),
    muted: oklchToHex(...),
    rule: oklchToHex(...),
  },
  // ... other themes
};

The OKLCH values here must match those in

colours.css

. When theme colours change, update both files.

Favicons

Per-theme favicons (

public/sf-*.ico

) are static binary files. No programmatic generation—must be manually created when adding themes or changing brand colours.

RSS Stylesheet

public/rss/styles.xsl

uses hardcoded hex values for browser rendering. Currently locked to steel theme. Optional to update when steel changes.

Checklists

Modifying a Token

Change value in appropriate
```
src/styles/tokens/*.css
```
file
Verify value aligns to 8px grid (for spacing/sizing/line-height)
Check for hardcoded duplicates in
```
palette.ts
```
if colour-related
Run
```
npm run check
```
to verify no type errors
Visual review across themes in browser

Modifying Theme Colours

Update
```
src/styles/tokens/colours.css
```
Update
```
src/styles/components/shiki.css
```
if affects syntax tokens
Update
```
src/lib/theme/palette.ts
```
with hex equivalents
Update favicon if brand colour changes
Update RSS XSL if steel theme changes (optional)
Test OG image generation at
```
/og/default.png
```

Adding a New Theme

Add to

THEME_ORDER

and

THEME_LABELS

src/config/themes.ts

Add colour block in
```
src/styles/tokens/colours.css
```
Add syntax overrides in
```
src/styles/components/shiki.css
```
Add OKLCH values in
```
src/lib/theme/palette.ts
```
Create
```
public/sf-[theme].ico
```
(manual—use favicon generator tool)
Test theme switcher cycles correctly
Test code blocks render with correct syntax colours
Test OG images generate with correct colours