@persona/design-system 0.3.0 → 0.4.0

package/skills/ui-authoring/TOKENS.md

@@ -0,0 +1,400 @@
+# Design Tokens
+
+How to pick values from `@persona/design-tokens`, plus the `Color` / `Spacing` / `Typography` catalog.
+
+```tsx
+import { BorderRadius, ChartingColors, Color, Spacing, Typography } from '@persona/design-tokens';
+```
+
+## Color
+
+`Color` is an enum of named colors organized by purpose (`Text*`, `Background*`, `Border*`, and
+others), plus a `Core*` palette and a `Primary*` brand set.
+
+Use according to this priority:
+
+1. Purpose-named `Color.*` (`Text*`, `Background*`, `Border*`, …)
+2. `Color.Core*` / `Color.Primary*` with a comment explaining the choice. For `Core*`, that comment is an `oxlint-disable-next-line persona-web/no-core-color-tokens`.
+3. Hardcoded hex (only if absolutely necessary) with a comment explaining the choice.
+
+```tsx
+// ❌ Color.CorePurple500  /  Color.PrimaryPurple  /  #3F48FD
+// ✅ Color.TextActive  /  Color.BackgroundButtonPrimary
+```
+
+| Need | Use |
+|------|-----|
+| Text | `Color.TextPrimary` / `TextSecondary` / `TextInverse` / `TextActive` / `TextDanger` / `TextDisabled` |
+| Page / card background | `Color.BackgroundPrimary` / `BackgroundSecondary` |
+| Borders | `Color.BorderHairline` / `BorderDivider` / `BorderFocus` |
+| Buttons | `Color.BackgroundButtonPrimary` (and Default / Danger + Hover variants) |
+| Inputs | `Color.BackgroundInputDefault` / `BorderInputDefault` |
+| Charts | `ChartingColors.Sequential` or `.Categorical` |
+
+```tsx
+const Panel = styled.div`
+  background-color: ${Color.BackgroundPrimary};
+  border: 1px solid ${Color.BorderDivider};
+  color: ${Color.TextPrimary};
+
+  &:hover {
+    background-color: ${Color.BackgroundSecondary};
+  }
+`;
+```
+
+### Core
+
+Each core color has shades from 50 (lightest) to 1100 (darkest):
+
+```tsx
+// Purple
+Color.CorePurple50     // #F4F5FF (lightest)
+Color.CorePurple100
+Color.CorePurple500    // Mid-range purple
+Color.CorePurple700
+Color.CorePurple1100   // #010334 (darkest)
+
+// Other core colors follow same pattern:
+// CoreRed, CoreOrange, CoreYellow, CoreGreen, CoreTeal, CoreBlue, CoreSlate
+```
+
+### Primary
+
+```tsx
+Color.PrimaryBlack    // #000000
+Color.PrimaryWhite    // #FFFFFF
+Color.PrimaryPurple   // #3F48FD (brand purple)
+Color.PrimaryRed      // #F04B38
+Color.PrimaryOrange   // #F59602
+Color.PrimaryYellow   // #DFFD2F
+Color.PrimaryGreen    // #41D49D
+Color.PrimaryTeal     // #36EBFD
+Color.PrimaryBlue     // #2B7FFD
+```
+
+### Background
+
+```tsx
+Color.BackgroundPrimary      // #FFFFFF (main background)
+Color.BackgroundSecondary    // #F5F5F6
+
+// Button backgrounds
+Color.BackgroundButtonDefault
+Color.BackgroundButtonDefaultHover
+Color.BackgroundButtonPrimary
+Color.BackgroundButtonPrimaryHover
+Color.BackgroundButtonDanger
+Color.BackgroundButtonDangerHover
+
+// Input backgrounds
+Color.BackgroundInputDefault
+Color.BackgroundInputActive
+Color.BackgroundInputDisabled
+
+// Label backgrounds
+Color.BackgroundLabelGrey
+Color.BackgroundLabelPurple
+Color.BackgroundLabelRed
+Color.BackgroundLabelGreen
+// ... and more label variants
+
+// Status indicator backgrounds
+Color.BackgroundStatusIndicatorSuccess
+Color.BackgroundStatusIndicatorWarning
+Color.BackgroundStatusIndicatorCritical
+Color.BackgroundStatusIndicatorFeature
+```
+
+### Text
+
+```tsx
+Color.TextPrimary      // #313131 (main text)
+Color.TextSecondary    // #707070 (secondary text)
+Color.TextInverse      // #FFFFFF (text on dark backgrounds)
+Color.TextActive       // #3F48FD (active/link text)
+Color.TextDanger       // #B81F0E (error text)
+Color.TextDisabled     // #BDBDBD (disabled text)
+
+// Status indicator text colors
+Color.TextStatusIndicatorSuccess
+Color.TextStatusIndicatorWarning
+Color.TextStatusIndicatorCritical
+```
+
+### Border
+
+```tsx
+Color.BorderHairline     // #F1F1F2 (subtle border)
+Color.BorderDivider      // #E2E2E3 (section divider)
+Color.BorderFocus        // #2B7FFD (focus state)
+
+// Input borders
+Color.BorderInputDefault
+Color.BorderInputHover
+Color.BorderInputActive
+Color.BorderInputWarning
+Color.BorderInputDanger
+Color.BorderInputDisabled
+
+// Icon borders
+Color.BorderIconPrimary
+Color.BorderIconSecondary
+Color.BorderIconActive
+Color.BorderIconSuccess
+Color.BorderIconWarning
+Color.BorderIconDanger
+```
+
+## Spacing
+
+`Spacing` is an enum of fixed gaps from `0` to `56px` (`Spacing[0]`–`Spacing[9]`).
+
+Use according to this priority:
+
+1. `Spacing[0–9]`
+2. Hardcoded px (multiple of 4, only if absolutely necessary); comment what it's doing
+
+Pass `Spacing[n]` into `Stack` / `HStack` `spacing` — do not set `gap` on a styled flex wrapper.
+
+```tsx
+// ❌ gap: 18px;
+// ✅ spacing={Spacing[4]}  /  padding: ${Spacing[5]};
+// ✅ padding: 72px; /* hero offset; no Spacing step */
+```
+
+| Need | Use |
+|------|-----|
+| Icon-to-text, tight groupings | `Spacing[1]`–`Spacing[2]` |
+| Form field padding, button padding | `Spacing[3]`–`Spacing[4]` |
+| Section margins, card padding | `Spacing[5]` |
+| Component spacing, page sections | `Spacing[6]`–`Spacing[7]` |
+| Hero sections, major divisions | `Spacing[8]`–`Spacing[9]` |
+
+```tsx
+const Container = styled.div`
+  padding: ${Spacing[5]};
+  margin-bottom: ${Spacing[4]};
+`;
+```
+
+### Scale
+
+```tsx
+Spacing[0]   // "0px"
+Spacing[1]   // "4px"
+Spacing[2]   // "8px"
+Spacing[3]   // "12px"
+Spacing[4]   // "16px"
+Spacing[5]   // "24px"
+Spacing[6]   // "32px"
+Spacing[7]   // "40px"
+Spacing[8]   // "48px"
+Spacing[9]   // "56px"
+```
+
+## Typography
+
+`Typography` is a set of complete type styles (`fontFamily`, `fontWeight`, `lineHeight`, `fontSize`,
+`textDecoration`).
+
+**IMPORTANT:** Never assemble type from individual `FontSize` / `FontWeight` / `FontFamily` tokens or hardcoded sizes.
+
+Use according to this priority:
+
+1. `Heading` / `Paragraph` / `Label`
+2. Complete `Typography.*` style
+
+`Paragraph` defaults to `color="secondary"` (grey). Use `color="primary"` for body that should read
+as main text.
+
+```tsx
+// ❌ font-size: 14px; font-weight: 500;
+// ✅ <Paragraph size="md">…</Paragraph>
+// ✅ ${Typography.TextMedium}
+```
+
+| Need | Use |
+|------|-----|
+| Headers and hero sections | `Typography.DisplayLarge` / `DisplayMedium` / `DisplaySmall` |
+| Section headers and sub-headers | `Heading` / `Typography.HeadingLarge`–`HeadingExtraSmall` |
+| Body copy and UI text | `Paragraph` / `Typography.TextMedium` |
+| Caption / helper | `Paragraph` `size="sm"` / `Typography.TextSmall` |
+| Form label | `Label` |
+| Code | `Typography.TextMono` |
+
+Each `Typography` style is a complete `PDSTypeStyle`:
+
+```tsx
+type PDSTypeStyle = {
+  fontFamily: FontFamily;
+  fontWeight: FontWeight;
+  lineHeight: LineHeight;
+  fontSize: FontSize;
+  textDecoration: TextDecoration;
+};
+```
+
+Styled components usage:
+
+```tsx
+const Heading = styled.h1`
+  ${Typography.HeadingLarge}
+  color: ${Color.TextPrimary};
+`;
+
+const BodyText = styled.p`
+  ${Typography.TextMedium}
+  color: ${Color.TextSecondary};
+`;
+
+const SmallLabel = styled.span`
+  ${Typography.TextSmall}
+  color: ${Color.TextSecondary};
+`;
+```
+
+### Display
+
+```tsx
+Typography.DisplayLarge    // 64px, bold
+Typography.DisplayMedium   // 48px, bold
+Typography.DisplaySmall    // 36px, bold
+```
+
+### Heading
+
+```tsx
+Typography.HeadingLarge       // 28px
+Typography.HeadingMedium      // 24px
+Typography.HeadingSmall       // 20px
+Typography.HeadingExtraSmall  // 16px
+```
+
+### Text / paragraph
+
+```tsx
+Typography.TextLarge          // 16px, regular
+Typography.TextLargeBold      // 16px, bold
+Typography.TextLargeLight     // 16px, light
+
+Typography.TextMedium         // 14px, regular — most common body
+Typography.TextMediumBold     // 14px, bold
+Typography.TextMediumLight    // 14px, light
+Typography.TextMediumLink     // 14px, regular, underlined
+
+Typography.TextSmall          // 12px, regular
+Typography.TextSmallBold      // 12px, bold
+Typography.TextSmallLink      // 12px, regular, underlined
+Typography.TextExtraSmall     // 10px
+
+Typography.TextMono           // 14px, monospace
+```
+
+## Radius
+
+`BorderRadius` is a small set of corner radii.
+
+Use according to this priority:
+
+1. `BorderRadius.Sm` / `Md` / `Lg` / `Xl` / `Circle`
+2. Hardcoded value (only if absolutely necessary); comment what it's doing
+
+| Need | Use |
+|------|-----|
+| Subtle rounding on small interactive elements (Checkboxes) | `BorderRadius.Sm` |
+| Inputs, Menus, Banners, Buttons | `BorderRadius.Md` |
+| Cards, Modals | `BorderRadius.Lg` |
+| Pills, larger rounding | `BorderRadius.Xl` |
+| Circular components (Radio Buttons) | `BorderRadius.Circle` |
+
+```tsx
+const Card = styled.div`
+  border-radius: ${BorderRadius.Lg};
+`;
+```
+
+### Scale
+
+```tsx
+BorderRadius.Sm      // 3px
+BorderRadius.Md      // 4px
+BorderRadius.Lg      // 8px
+BorderRadius.Xl      // 12px
+BorderRadius.Circle  // 50%
+```
+
+## Elevation
+
+`Elevation` is a set of box-shadows for stacking UI. Import it from
+`@persona/design-system/variables/effect` — it is not in `@persona/design-tokens`.
+
+```tsx
+import { Elevation } from '@persona/design-system/variables/effect';
+```
+
+Use according to this priority:
+
+1. `Elevation.Low` / `Mid` / `High`
+2. Custom shadow (only if absolutely necessary); comment what it's doing
+
+| Need | Use |
+|------|-----|
+| Menus, Popovers | `Elevation.Low` |
+| Cards, Date Pickers | `Elevation.Mid` |
+| Modals | `Elevation.High` |
+
+```tsx
+const Menu = styled.div`
+  box-shadow: ${Elevation.Low};
+`;
+```
+
+## Charts
+
+Use `recharts` for all chart components.
+
+Use according to this priority:
+
+1. `ChartingColors.Sequential` (ordered / numeric) or `ChartingColors.Categorical` (unordered)
+2. Hardcoded hex (only if absolutely necessary) with a comment explaining the choice.
+
+`Categorical` is for light backgrounds. If you exceed the max series, group leftover items or link
+to an export — do not invent extra hex colors.
+
+| Need | Use | Max series |
+|------|-----|------------|
+| Numeric / ordered | `ChartingColors.Sequential` | 8 |
+| Categorical / unordered | `ChartingColors.Categorical` | 14 |
+
+```tsx
+<Pie data={data} dataKey="value">
+  {data.map((_, i) => (
+    <Cell key={i} fill={ChartingColors.Categorical[i % ChartingColors.Categorical.length]} />
+  ))}
+</Pie>
+```
+
+## Token Verification
+
+To explore available tokens in your project:
+
+```bash
+# Search for color definitions
+grep -r "Color\." node_modules/@persona/design-tokens/dist/js/colors.d.ts
+
+# Check spacing values
+cat node_modules/@persona/design-tokens/dist/js/spacing.d.ts
+
+# See typography styles
+cat node_modules/@persona/design-tokens/dist/js/typography.d.ts
+```
+
+Or check programmatically:
+
+```tsx
+import * as DesignTokens from '@persona/design-tokens';
+console.log(DesignTokens.Color);
+console.log(DesignTokens.Spacing);
+console.log(DesignTokens.Typography);
+```