Skip to content

Commit a2254fd

Browse files
cylewaitforitalexdlnghostdevvcoderabbitai[bot]
authored
docs(ui): add design system guidelines (#2252)
Co-authored-by: Alex Savelyev <91429106+alexdln@users.noreply.github.com> Co-authored-by: Willow (GHOST) <git@willow.sh> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
1 parent eb4d862 commit a2254fd

8 files changed

Lines changed: 469 additions & 99 deletions

File tree

‎.storybook/docs/colors.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks'
2+
import { theme } from '../../uno.theme.ts'
3+
4+
<Meta title="Colors" tags={['hide-toolbar']} />
5+
6+
# Colors
7+
8+
The npmx color system is built on CSS custom properties with support for light/dark themes and multiple background variants.
9+
10+
Color values are defined in `uno.theme.ts`.
11+
12+
## Background Colors
13+
14+
<ColorPalette>
15+
<ColorItem
16+
title="Background"
17+
subtitle="Main background colors"
18+
colors={Object.entries(theme.colors.bg).reduce(
19+
(acc, [key, value]) => ({
20+
...acc,
21+
[key === 'DEFAULT' ? 'bg' : `bg-${key}`]: value,
22+
}),
23+
{},
24+
)}
25+
/>
26+
</ColorPalette>
27+
28+
## Foreground Colors
29+
30+
<ColorPalette>
31+
<ColorItem
32+
title="Foreground"
33+
subtitle="Text and content colors"
34+
colors={Object.entries(theme.colors.fg).reduce(
35+
(acc, [key, value]) => ({
36+
...acc,
37+
[key === 'DEFAULT' ? 'fg' : `fg-${key}`]: value,
38+
}),
39+
{},
40+
)}
41+
/>
42+
</ColorPalette>
43+
44+
## Border Colors
45+
46+
<ColorPalette>
47+
<ColorItem
48+
title="Border"
49+
subtitle="Border and separator colors"
50+
colors={Object.entries(theme.colors.border).reduce(
51+
(acc, [key, value]) => ({
52+
...acc,
53+
[key === 'DEFAULT' ? 'border' : `border-${key}`]: value,
54+
}),
55+
{},
56+
)}
57+
/>
58+
</ColorPalette>
59+
60+
## Accent Colors
61+
62+
<ColorPalette>
63+
<ColorItem
64+
title="Primary Accent"
65+
subtitle="User-settable accent color"
66+
colors={Object.entries(theme.colors.accent).reduce(
67+
(acc, [key, value]) => ({
68+
...acc,
69+
[key === 'DEFAULT' ? 'accent' : `accent-${key}`]: value,
70+
}),
71+
{},
72+
)}
73+
/>
74+
</ColorPalette>
75+
76+
## Syntax Highlighting
77+
78+
<ColorPalette>
79+
<ColorItem
80+
title="Syntax"
81+
subtitle="Code syntax highlighting colors"
82+
colors={theme.colors.syntax}
83+
/>
84+
</ColorPalette>
85+
86+
## Badge Colors
87+
88+
<ColorPalette>
89+
<ColorItem
90+
title="Badges"
91+
subtitle="Badge background and text colors"
92+
colors={theme.colors.badge}
93+
/>
94+
</ColorPalette>
95+
96+
## Provider Brand Colors
97+
98+
<ColorPalette>
99+
<ColorItem
100+
title="Provider Brand Colors"
101+
subtitle="Playground provider and framework brand colors"
102+
colors={theme.colors.provider}
103+
/>
104+
</ColorPalette>
105+
106+
---
107+
108+
## Related
109+
110+
- [Design System Guidelines](https://storybook.npmx.dev/?path=/docs/guidelines--docs)

‎.storybook/docs/guidelines.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
import { Meta } from '@storybook/addon-docs/blocks'
2+
3+
<Meta title="Guidelines" tags={['hide-toolbar']} />
4+
5+
# Guidelines
6+
7+
## Containers
8+
9+
We use three container types depending on content density.
10+
11+
**Main Container** is the default layout container. It should be used for pages with minimal or non-text content (e.g. graphs, dashboards).
12+
13+
**Content Container** is used for text-heavy layouts. All long-form content must be placed inside this container. The maximum readable width is **768px**.
14+
15+
**Extra Container** is used for dense layouts (e.g. code, detailed views) where additional horizontal space is required.
16+
17+
A right sidebar (304px) may be used for secondary content when needed.
18+
19+
Text and input fields should not exceed **768px** in width
20+
21+
## Element Sizes
22+
23+
Interactive element sizes:
24+
25+
- 24 — 2xs (rare)
26+
- 28 — xs (compact)
27+
- 32 — sm (minimum recommended)
28+
- 36 — md (default)
29+
- 42 — lg
30+
- 48 — xl
31+
- 56 — 2xl
32+
- 64 — 3xl
33+
34+
## Typography
35+
36+
- Base font size: **16px**
37+
- Minimum font size: **14px** (use sparingly)
38+
39+
Text casing:
40+
41+
- **Uppercase** — for headings
42+
- **Lowercase** — for UI elements
43+
- **Normal** - for body content
44+
45+
[See Typography](https://storybook.npmx.dev/?path=/docs/tokens-typography--docs)
46+
47+
## Surfaces & Sections
48+
49+
To visually separate content blocks (grouped content, cards, settings sections), use subtle background variations:
50+
51+
- `bg-muted`
52+
- `bg-subtle`
53+
54+
## Borders & Radius
55+
56+
- subtle border
57+
- light border radius
58+
- soft "glass-like" appearance
59+
60+
Only avatars should have fully circular shapes.
61+
62+
## Colors
63+
64+
- Primary surfaces: **white** (`fg`)
65+
- Secondary or less important content: use softer, muted tones
66+
67+
[See Colors](https://storybook.npmx.dev/?path=/docs/tokens-colors--docs)
68+
69+
## Layout Stability
70+
71+
Interfaces must remain visually stable across screens and pages. Avoid layout shifts. If shifts are unavoidable, place elements where movement is not critical to user interaction.
72+
73+
## Responsiveness specifics
74+
75+
On smaller screens:
76+
77+
- Button text may be hidden (icons only)
78+
- Keyboard shortcuts may be hidden
79+
80+
## General Principles
81+
82+
- Preserve the meaning of elements (avoid links like button, etc)
83+
- Maintain sufficient spacing
84+
- Keep interfaces accessible
85+
- Prefer simple, predictable layouts
86+
- Design components to be easy to implement and scale

‎.storybook/docs/typography.mdx‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
import { Meta, Typeset } from '@storybook/addon-docs/blocks'
2+
import { theme } from '../../uno.theme.ts'
3+
4+
<Meta title="Typography" tags={['hide-toolbar']} />
5+
6+
export const wind4FontSizes = {
7+
'xs': '0.75rem',
8+
'sm': '0.875rem',
9+
'base': '1rem',
10+
'lg': '1.125rem',
11+
'xl': '1.25rem',
12+
'2xl': '1.5rem',
13+
'3xl': '1.875rem',
14+
'4xl': '2.25rem',
15+
'5xl': '3rem',
16+
}
17+
18+
# Typography
19+
20+
The npmx typography system uses Geist for sans-serif text and Geist Mono for monospace code.
21+
22+
Typography values are defined in `uno.theme.ts`.
23+
24+
## Font Families
25+
26+
### Sans Serif — Geist
27+
28+
<Typeset
29+
fontFamily={theme.font.sans}
30+
fontSizes={[
31+
wind4FontSizes['base'], // 16px
32+
]}
33+
fontWeight={400}
34+
sampleText="The quick brown fox jumps over the lazy dog"
35+
/>
36+
37+
<Typeset
38+
fontFamily={theme.font.sans}
39+
fontSizes={[
40+
wind4FontSizes['5xl'], // 48px
41+
wind4FontSizes['4xl'], // 36px
42+
wind4FontSizes['3xl'], // 30px
43+
wind4FontSizes['2xl'], // 24px
44+
wind4FontSizes['xl'], // 20px
45+
wind4FontSizes['lg'], // 18px
46+
wind4FontSizes['base'], // 16px
47+
wind4FontSizes['sm'], // 14px
48+
wind4FontSizes['xs'], // 12px
49+
theme.text['2xs'].fontSize, // 11px
50+
theme.text['3xs'].fontSize, // 10px
51+
theme.text['4xs'].fontSize, // 9px
52+
theme.text['5xs'].fontSize, // 8px
53+
]}
54+
fontWeight={400}
55+
sampleText="The quick brown fox jumps over the lazy dog"
56+
/>
57+
58+
### Monospace — Geist Mono
59+
60+
Code and monospace typography scale:
61+
62+
<Typeset
63+
fontFamily={theme.font.mono}
64+
fontSizes={[
65+
wind4FontSizes['base'], // 16px
66+
]}
67+
fontWeight={400}
68+
sampleText="const greeting = 'Hello, World!';"
69+
/>
70+
71+
<Typeset
72+
fontFamily={theme.font.mono}
73+
fontSizes={[
74+
wind4FontSizes['5xl'], // 48px
75+
wind4FontSizes['4xl'], // 36px
76+
wind4FontSizes['3xl'], // 30px
77+
wind4FontSizes['2xl'], // 24px
78+
wind4FontSizes['xl'], // 20px
79+
wind4FontSizes['lg'], // 18px
80+
wind4FontSizes['base'], // 16px
81+
wind4FontSizes['sm'], // 14px
82+
wind4FontSizes['xs'], // 12px
83+
theme.text['2xs'].fontSize, // 11px
84+
theme.text['3xs'].fontSize, // 10px
85+
theme.text['4xs'].fontSize, // 9px
86+
theme.text['5xs'].fontSize, // 8px
87+
]}
88+
fontWeight={400}
89+
sampleText="const greeting = 'Hello, World!';"
90+
/>
91+
92+
## Font Sizes
93+
94+
The complete typography scale combines custom micro sizes (`5xs`-`2xs` from our theme) with standard Wind4 preset sizes (`xs`-`5xl`).
95+
96+
**Custom Micro Sizes (from `theme.text`):**
97+
98+
- `5xs` = {theme.text['5xs'].fontSize} (8px)
99+
- `4xs` = {theme.text['4xs'].fontSize} (9px)
100+
- `3xs` = {theme.text['3xs'].fontSize} (10px)
101+
- `2xs` = {theme.text['2xs'].fontSize} (11px)
102+
103+
**Wind4 Standard Sizes:**
104+
105+
- `xs` = {wind4FontSizes['xs']} (12px)
106+
- `sm` = {wind4FontSizes['sm']} (14px)
107+
- `base` = {wind4FontSizes['base']} (16px)
108+
- `lg` = {wind4FontSizes['lg']} (18px)
109+
- `xl` = {wind4FontSizes['xl']} (20px)
110+
- `2xl` = {wind4FontSizes['2xl']} (24px)
111+
- `3xl` = {wind4FontSizes['3xl']} (30px)
112+
- `4xl` = {wind4FontSizes['4xl']} (36px)
113+
- `5xl` = {wind4FontSizes['5xl']} (48px)
114+
115+
## Font Weights
116+
117+
<Typeset
118+
fontFamily={theme.font.sans}
119+
fontSizes={['1rem']}
120+
fontWeight={300}
121+
sampleText="Light (300) — Used sparingly for decorative purposes"
122+
/>
123+
124+
<Typeset
125+
fontFamily={theme.font.sans}
126+
fontSizes={['1rem']}
127+
fontWeight={400}
128+
sampleText="Regular (400) — Default weight for body text and most content"
129+
/>
130+
131+
<Typeset
132+
fontFamily={theme.font.sans}
133+
fontSizes={['1rem']}
134+
fontWeight={500}
135+
sampleText="Medium (500) — Used for emphasis and section headings"
136+
/>
137+
138+
<Typeset
139+
fontFamily={theme.font.sans}
140+
fontSizes={['1rem']}
141+
fontWeight={600}
142+
sampleText="Semibold (600) — Used for strong emphasis and primary actions"
143+
/>
144+
145+
<Typeset
146+
fontFamily={theme.font.sans}
147+
fontSizes={['1rem']}
148+
fontWeight={700}
149+
sampleText="Bold (700) — Used for headings and important labels"
150+
/>
151+
152+
## Line Height
153+
154+
Base line height is set to **1.6** for optimal readability. This provides comfortable spacing for multi-line text blocks while maintaining density for UI components.
155+
156+
## Typography Features
157+
158+
- **Font smoothing**: Antialiased rendering (`-webkit-font-smoothing: antialiased`) applied globally
159+
- **Text rendering**: `optimizeLegibility` applied globally for consistent cross-browser rendering
160+
161+
---
162+
163+
## Related
164+
165+
- [Design System Guidelines](https://storybook.npmx.dev/?path=/docs/guidelines--docs) - See typography guidelines and usage
166+
- [Colors](https://storybook.npmx.dev/?path=/docs/colors--docs) - View the color system

.storybook/storybook-welcome.mdx renamed to .storybook/docs/welcome.mdx

File renamed without changes.

‎.storybook/main.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
import type { StorybookConfig } from '@storybook-vue/nuxt'
22

33
const config = {
4-
stories: ['../.storybook/*.mdx', '../app/**/*.stories.@(js|ts)'],
4+
stories: [
5+
// List welcome first in sidebar
6+
'../.storybook/docs/welcome.mdx',
7+
'../.storybook/docs/*.mdx',
8+
'../app/**/*.@(mdx|stories.@(js|ts))',
9+
],
510
addons: [
611
'@storybook/addon-a11y',
712
'@storybook/addon-docs',

‎chromatic.config.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@
33
"onlyChanged": true,
44
"autoAcceptChanges": "main",
55
"exitZeroOnChanges": false,
6-
"externals": [".storybook/**", "uno.config.ts"]
6+
"externals": [".storybook/**", "uno.config.ts", "uno.theme.ts"]
77
}

0 commit comments

Comments
 (0)