Olympus MUI Design System

The single source of truth for design tokens used across all projects. Built on Material UI and the Olympus MUI Figma library.

What's Inside

| File | Purpose | |---|---| | src/olympusTheme.ts | MUI theme with all colors, typography, spacing, shadows (runtime code) | | claude-skill/SKILL.md | Claude Code skill that enforces the design system in AI-generated code |

For Designers

Your workflow stays the same — design in Figma using the Olympus MUI library. This repo is the bridge between Figma and code.

When you update tokens in Figma:

1. Tell your developer which tokens changed (color, typography, spacing, etc.)
2. They update the values in src/olympusTheme.ts
3. They bump the version and publish
4. All projects get the update on next npm update

What the Claude skill does:

When developers use Claude Code (AI coding assistant), the skill file forces Claude to ONLY use Olympus tokens. If a developer asks Claude to use a color like #FF0000, Claude will warn them and suggest the correct Olympus token (error.main: #FF3333). This keeps every project consistent with your Figma designs.

For Developers

Step 1: Install the theme

npm install @sachinsinha0/olympus-theme

Step 2: Wrap your app

import { ThemeProvider } from '@mui/material/styles';
import { lightTheme } from '@sachinsinha0/olympus-theme';

function App() {
  return (
    <ThemeProvider theme={lightTheme}>
      {/* your app */}
    </ThemeProvider>
  );
}

Step 3: Install the Claude skill (one time per project)

npm run setup:claude

This copies the skill file into .claude/skills/olympus-mui/SKILL.md. Commit it to your repo so the whole team gets it.

Step 4: Use tokens in your code

// Colors — always use theme tokens, never hex values
<Box sx={{ bgcolor: 'primary.main', color: 'text.primary' }} />

// Typography — always use variants
<Typography variant="h1">Heading</Typography>
<Typography variant="body2">Body text</Typography>

// Spacing — always use theme.spacing()
<Box sx={{ p: 3, m: 2 }} />  // p=16px, m=8px

// Shadows — always use elevation
<Paper elevation={2}>...</Paper>

Dark mode

import { darkTheme } from '@sachinsinha0/olympus-theme';

<ThemeProvider theme={darkTheme}>
  {/* automatically switches all tokens */}
</ThemeProvider>

Quick Token Reference

Colors

| Token | Light | Dark | Code | |---|---|---|---| | Primary | #196AE5 | #66BBFF | theme.palette.primary.main | | Error | #FF3333 | #F44336 | theme.palette.error.main | | Warning | #FF9800 | #FFCC80 | theme.palette.warning.main | | Success | #22BB34 | #66BB6A | theme.palette.success.main | | Info | #196AE5 | #29B6F6 | theme.palette.info.main |

Typography (Font: Inter)

| Style | Size | Weight | Code | |---|---|---|---| | Headline 1 | 32px | SemiBold | variant="h1" | | Headline 2 | 28px | SemiBold | variant="h2" | | Headline 3 | 24px | SemiBold | variant="h3" | | Body 1 | 16px | Regular | variant="body1" | | Body 2 | 14px | Regular | variant="body2" | | Caption | 12px | Regular | variant="caption" |

Spacing

| Token | Value | Code | |---|---|---| | 1 | 4px | theme.spacing(1) | | 2 | 8px | theme.spacing(2) | | 3 | 16px | theme.spacing(3) | | 4 | 24px | theme.spacing(4) | | 5 | 32px | theme.spacing(5) |

See claude-skill/SKILL.md for the complete token reference.

Repo Structure

olympus-design-system/
├── src/
│   ├── index.ts              # Package entry point
│   └── olympusTheme.ts       # All design tokens as MUI theme
├── claude-skill/
│   └── SKILL.md              # Claude Code enforcement rules
├── setup-claude-skill.sh     # One-command skill installer
├── package.json
├── tsconfig.json
└── README.md

Updating Tokens

1. Edit values in src/olympusTheme.ts
2. Update the matching values in claude-skill/SKILL.md
3. Bump version in package.json
4. Publish: npm publish
5. In each project: npm update @sachinsinha0/olympus-theme