Resources / Developer Tools
Developer Tools
Everything a developer needs to implement Champagne Paper correctly — the design skill for AI-assisted development, the master token reference, and links to all source documents.
Design Skill
Drop xuperson-design-skill.md into your project's
.claude/skills/ directory. Claude Code picks it up
automatically and enforces Champagne Paper conventions whenever you build UI.
Modelled after the official
Anthropic brand-guidelines skill pattern.
01
Copy the skill file
Copy xuperson-design-skill.md to your project root or .claude/skills/
02
Open Claude Code
The skill is auto-discovered. Check /skills to confirm it loaded.
03
Build with confidence
Claude now enforces the design system on every component it writes.
xuperson-design-skill.md (condensed)
SKILL---
name: xuperson-design
description: Use when building, styling, or reviewing UI components for the Xuperson Institute
ecosystem. Enforces the "Champagne Paper" design system.
---
# Xuperson Design & Styling
## Core Design Principles
### 1. The Paper World (Surfaces & Ink)
- Base surfaces: --background (#FCFCFA light / #161520 dark). NEVER pure white/black.
- Warm ink shadows only. Never cold neutral grays.
### 2. Architectural Typography
- Oswald: all UI labels, navigation, buttons, H2–H4.
- Instrument Serif: H1 and display headlines ONLY.
- Instrument Sans: all body copy, form labels, table content.
- Space Mono: code, metadata, timestamps, token names.
### 3. Restricted AI Gradient (fuchsia → violet → cyan)
- Permitted: icon fills, 2px glow borders, indicator dots, thin dividers.
- Forbidden: text fills, button backgrounds, large surface backgrounds.
### 4. Semantic Tokens (always use CSS vars, never raw hex)
- bg-primary / text-primary-foreground — burgundy CTA
- bg-card / text-card-foreground — card surfaces
- bg-muted / text-muted-foreground — secondary content
- border-border — all borders and dividers
### 5. Common Mistakes
- Cold shadows: use hsl(37 40% 8% / 0.18) not rgba(0,0,0,0.1)
- Typography drift: never Instrument Serif for labels or nav
- Gradient proliferation: the AI gradient is a signal, not decoration
- Architectural radii: rounded-sm (4px) for buttons/badges, rounded-lg (10px) for cardsdesign.md Reference
docs/design-system/design.md is the single-file
design system reference — all tokens, rules, and component specs assembled into one document.
Ideal for providing full context to AI agents in a single file attachment.
Purpose
Assembled from all 12 design system markdown files. When an AI agent needs the
complete design system in one prompt attachment, use design.md.
When to Use
- · Starting a new feature from scratch
- · Reviewing a component for DS compliance
- · Generating full page layouts
- · Auditing existing code for deviations
docs/design-system/design.md Single-file · AI-optimised Token Quick Reference
The 10 most-used CSS custom properties. Always use semantic tokens in component code —
never raw hex values. Both themes are set in global.css.
| Token | Role | ||
|---|---|---|---|
--background | #FCFCFA | #161520 | Page/base surface |
--foreground | #1B1B27 | #FCFCF5 | Primary text |
--card | #FCFCF5 | #211F2B | Card surfaces |
--primary | #800020 | #E8C98A | CTAs, links, burgundy |
--primary-foreground | #FCFCE9 | #1C160C | Text on primary |
--muted | #F6F1E7 | #242130 | Subtle backgrounds |
--muted-foreground | #6F575F | #C6BCAB | Secondary text |
--border | #D8CAB2 | #4B4458 | All borders |
--accent | #FCFCE9 | #E8C98A | Champagne accent bg |
--destructive | #B42318 | #F87171 | Errors |
Source Documents
All design decisions are documented in docs/design-system/.
Each file is standalone and can be passed individually to an AI agent for focused tasks.
design.md docs/design-system/design.md Master single-file reference. All tokens, rules, and patterns assembled in one document for AI agent consumption.
00-overview.md docs/design-system/00-overview.md Design philosophy, brand voice, and dual-personality (academic + corporate) concept.
01-color-tokens.md docs/design-system/01-color-tokens.md Full color token reference — all 24 semantic tokens with light/dark values.
02-typography.md docs/design-system/02-typography.md Font families, type scale (15 levels), pairing rules.
03-spacing-layout.md docs/design-system/03-spacing-layout.md Spacing scale, grid system, density modes, breakpoints.
04-components.md docs/design-system/04-components.md Button, card, badge, form, overlay component specs.
05-ai-gradient.md docs/design-system/05-ai-gradient.md AI gradient usage rules — permitted and forbidden uses.
06-motion.md docs/design-system/06-motion.md Easing curves, timing tokens, animation principles.
07-surface-shadow.md docs/design-system/07-surface-shadow.md Shadow elevation scale, paper texture, focus rings.
08-logo.md docs/design-system/08-logo.md Logo lockups, animations, clear space, forbidden uses.
12-domain-colors.md docs/design-system/12-domain-colors.md .com/.net/.org semantic color system — badge implementation.
xuperson-design-skill.md docs/xuperson-design-skill.md The full AI agent skill file. Drop into any Claude Code project to enforce Champagne Paper standards.