A code-first design system migrated from Figma, built on a 3-tier token architecture.
📖 Live Storybook: https://helloprincepal.github.io/PremUI_DesignSystem
Tip
AI Reference: If you are an AI assistant working on this repo, please refer to AI_PREMUI_REFERENCE.md for design system rules and architecture details.
- Foundations: Colors, Spacing, Radius, Shadows, Typography (Token synced)
- Styles: Dark Mode & Multi-accent support build pipeline
- Components:
- Accordion: Full interactive states, Figma-aligned padding, dynamic alignment logic.
- Alert: 3 sizes × 4 styles × 5 statuses, dismiss + action links.
- LinkButton: 2 sizes × 5 color styles, icons, underline, disabled.
- Button: 3 styles × 4 sizes, icon slots, icon-only, href support.
- Avatars: Modular layout for user avatars, initials, and size scaling.
- ActivityFeed: Dynamic status feeds, custom dates, action controls.
- Next Steps: Input, Modal, etc.
# Install dependencies
npm install
# Build CSS variables from tokens
npx style-dictionary build --config sd.config.jsThe system follows a strict 3-tier token hierarchy:
┌──────────────────────────────────┐
│ Component Tokens │ ← button padding, card radius
│ (tokens/component/) │ references semantic only
├──────────────────────────────────┤
│ Semantic Tokens │ ← bg/strong, text/soft, state/error
│ (tokens/semantic/) │ references core only
├──────────────────────────────────┤
│ Core Tokens │ ← gray.950, blue.500, radius.8
│ (tokens/core/) │ raw primitive values
└──────────────────────────────────┘
Rule: Components must never reference core tokens directly. Always go through semantic.
| File | Contents | Count |
|---|---|---|
colors.json |
10 palettes × 11 shades (gray, slate, blue, red, green, orange, yellow, purple, sky, pink, teal) | ~123 |
alpha.json |
Transparency overlays (24/16/10%) + shadow tints (8/6/4/2/0%) for 13 colors | ~65 |
spacing.json |
13-step scale: 0, 2, 4, 6, 8, 10, 12, 16, 24, 32, 40, 48 | 13 |
radius.json |
12-step scale: 0–28px + full (999px) |
12 |
shadows.json |
30+ shadows (regular, card, custom, colored, component, gradient) | 30+ |
typography.json |
Font families, weights, sizes, line-heights | — |
motion.json |
5 durations (100–500ms), 4 easings, transition shorthands | — |
layout.json |
12-column grid (24px gutter, 32px margin), sidebar widths | — |
| File | Contents |
|---|---|
light.json |
Light theme: static, bg, text, stroke, icon, state (10 intents), theme, overlay, social, illustration |
dark.json |
Dark theme: inverted mappings for all light categories |
theme.json |
Multi-mode primary color system (Blue/Purple/Orange/Green), each with 5 solid + 3 alpha + 5 shadow tints |
typography.json |
23 text styles: Title (h1–h6), Label (xl–xs), Paragraph (xl–xs), Subheading (xl–2xs), Doc (h1–h4) |
Apply via the data-theme attribute on any container:
<body data-theme="light"> <!-- default -->
<body data-theme="dark">Switch the primary accent color via data-theme-color:
<body data-theme-color="blue"> <!-- default -->
<body data-theme-color="purple">
<body data-theme-color="orange">
<body data-theme-color="green">All components using var(--primary-*) tokens update automatically.
12-column responsive grid built on CSS Grid:
<div class="grid-container">
<div class="col-span-4">Sidebar</div>
<div class="col-span-8">Content</div>
</div>- Columns: 12
- Gutter: 24px
- Margin: 32px
- Sidebar widths: 272px (default), 80px (collapsed), 200px (submenu)
Style Dictionary compiles JSON tokens → CSS custom properties.
npm run build:tokens
# or directly: npx style-dictionary build --config sd.config.js| Command | Description |
|---|---|
npm run storybook |
Start Storybook dev server at http://localhost:6006 |
npm run build:tokens |
Rebuild CSS variables from design tokens |
npm run build:storybook |
Build static Storybook |
npm run icons:generate |
Regenerate Storybook icon selector from installed remixicon |
| File | Selector | Purpose |
|---|---|---|
src/styles/variables.css |
:root |
Default (light + blue) variables |
src/styles/dark-theme.css |
[data-theme="dark"] |
Dark mode overrides |
src/styles/theme-purple.css |
[data-theme-color="purple"] |
Purple accent overrides |
src/styles/theme-orange.css |
[data-theme-color="orange"] |
Orange accent overrides |
src/styles/theme-green.css |
[data-theme-color="green"] |
Green accent overrides |
Remix Icon is the only approved icon library.
<i class="ri-home-line"></i>
<i class="ri-settings-3-fill"></i>
⚠️ Lucide, HeroIcons, FontAwesome, and all other icon libraries are strictly forbidden. This is enforced via.cursorrulesfor AI agents and must be followed by all contributors.
Browse available icons: https://remixicon.com
Components accept icon names without the ri- prefix. The prefix is applied internally at render time:
<Button leftIcon="add-line" rightIcon="arrow-right-s-line">Save</Button>
<LinkButton leftIcon="arrow-left-s-line">Back</LinkButton>Icon prop fields (e.g. leftIcon, rightIcon) show a searchable dropdown in the Storybook Controls panel listing all 3,000+ Remix Icons. The dropdown is driven by .storybook/remixIcons.ts, which is generated from the installed remixicon package and checked into source control.
When upgrading remixicon, regenerate the list and commit the result:
npm install remixicon@latest
npm run icons:generate
# then commit package.json, package-lock.json, and .storybook/remixIcons.tsThe generator reads node_modules/remixicon/fonts/remixicon.glyph.json and outputs .storybook/remixIcons.ts. It has no external dependencies — just Node.js. Source: scripts/generate-icon-list.js.
The premui.lib.pen file is the synchronized visual reference document. It contains all design tokens as Pencil variables, ensuring design ↔ code parity.
Open it in the Pencil app to inspect token swatches, spacing scales, and component previews.
- Never hardcode values — always use
var(--token-name)CSS custom properties. - Never bypass the token hierarchy — components → semantic → core.
- Never use non-Remix icons — enforced by
.cursorrules. - Rebuild after token changes — run the Style Dictionary build command.
- Update the changelog — document every token or component change.
ISC