ctc-component-library 0.3.0 → 1.0.0-alpha.4

package/DESIGN.md

@@ -0,0 +1,408 @@
+---
+version: alpha
+name: CTC Component Library
+description: Dual-brand (B2B green / B2C blue) React + TypeScript + SCSS atomic design system. Source of truth for tokens lives in src/foundationTokens/*.scss; the public TS exports under src/commons/* mirror the same scales (with a few documented drifts).
+colors:
+  gray-100: "#171a1a"
+  gray-80: "#303333"
+  gray-60: "#494d4b"
+  gray-40: "#b9bfbd"
+  gray-20: "#edf2f0"
+  gray-00: "#fcfffe"
+  primary-dark: "#001f19"
+  primary: "#1e5349"
+  primary-light: "#6be3d7"
+  primary-lighter: "#daf2f0"
+  secondary-dark: "#1d5bbc"
+  secondary: "#1d5bbc"
+  secondary-light: "#bfe1fc"
+  secondary-lighter: "#e2f2ff"
+  secondary-b2c: "#468eff"
+  secondary-b2c-hover: "#84b2fb"
+  purple-dark: "#5a52ad"
+  purple: "#756dc8"
+  purple-light: "#aea7f9"
+  purple-lighter: "#dddaff"
+  orange-dark: "#ac5734"
+  orange: "#e57b43"
+  orange-light: "#ffaa7d"
+  orange-lighter: "#ffefe7"
+  error: "#c00808"
+  error-hover: "#cc3939"
+  error-light: "#ffe5e5"
+  success: "#206614"
+  success-hover: "#4c8543"
+  success-light: "#e5ffea"
+  alert: "#9f760b"
+  alert-light: "#fff1cc"
+typography:
+  h1:
+    fontFamily: Roca One
+    fontSize: 56px
+    fontWeight: 300
+    lineHeight: 60px
+    letterSpacing: 1.5px
+  h2:
+    fontFamily: Roca One
+    fontSize: 48px
+    fontWeight: 300
+    lineHeight: 55px
+    letterSpacing: 1.2px
+  h3:
+    fontFamily: Roca One
+    fontSize: 34px
+    fontWeight: 300
+    lineHeight: 40px
+    letterSpacing: 1px
+  h4:
+    fontFamily: Roca One
+    fontSize: 24px
+    fontWeight: 300
+    lineHeight: 30px
+    letterSpacing: 0.8px
+  h5:
+    fontFamily: Roca One
+    fontSize: 20px
+    fontWeight: 300
+    lineHeight: 25px
+    letterSpacing: 0.6px
+  body-1:
+    fontFamily: NT Bau
+    fontSize: 24px
+    fontWeight: 400
+    lineHeight: 30px
+    letterSpacing: -0.5px
+  body-2:
+    fontFamily: NT Bau
+    fontSize: 20px
+    fontWeight: 400
+    lineHeight: 24px
+    letterSpacing: -0.5px
+  body-3:
+    fontFamily: NT Bau
+    fontSize: 18px
+    fontWeight: 400
+    lineHeight: 24px
+    letterSpacing: -0.5px
+  body-4:
+    fontFamily: NT Bau
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 22px
+    letterSpacing: -0.5px
+  body-5:
+    fontFamily: NT Bau
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 20px
+    letterSpacing: -0.5px
+  body-6:
+    fontFamily: NT Bau
+    fontSize: 12px
+    fontWeight: 400
+    lineHeight: 16px
+    letterSpacing: -0.5px
+  button-1:
+    fontFamily: NT Bau
+    fontSize: 18px
+    fontWeight: 400
+    lineHeight: 1
+    letterSpacing: -0.5px
+  button-2:
+    fontFamily: NT Bau
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 1
+    letterSpacing: -0.5px
+motion:
+  ease-out: "cubic-bezier(0.23, 1, 0.32, 1)"
+  ease-in-out: "cubic-bezier(0.77, 0, 0.175, 1)"
+  ease-drawer: "cubic-bezier(0.32, 0.72, 0, 1)"
+  duration-instant: 100ms
+  duration-fast: 160ms
+  duration-base: 200ms
+  duration-slow: 280ms
+  stagger-step: 35ms
+  press-scale: 0.97
+spacing:
+  zero: 0px
+  x1: 4px
+  x2: 8px
+  x3: 12px
+  x4: 16px
+  x5: 20px
+  x6: 24px
+  x8: 32px
+  x10: 40px
+  x12: 48px
+  x14: 56px
+  x16: 64px
+  x18: 72px
+  x20: 80px
+rounded:
+  x1: 4px
+  x2: 8px
+  x3: 12px
+  x4: 16px
+  x5: 20px
+  x6: 24px
+  x8: 32px
+  x10: 40px
+  x12: 48px
+  x14: 56px
+  x16: 64px
+  x18: 72px
+  x20: 80px
+components:
+  button-primary:
+    backgroundColor: "{colors.primary-light}"
+    textColor: "{colors.gray-80}"
+    rounded: "{rounded.x8}"
+    typography: "{typography.button-2}"
+  button-primary-hover:
+    backgroundColor: "{colors.primary-lighter}"
+    textColor: "{colors.gray-60}"
+  button-primary-disabled:
+    backgroundColor: "{colors.gray-20}"
+    textColor: "{colors.gray-40}"
+  button-primary-neutral:
+    backgroundColor: "{colors.gray-80}"
+    textColor: "{colors.gray-00}"
+  button-primary-neutral-hover:
+    backgroundColor: "{colors.gray-60}"
+    textColor: "{colors.gray-20}"
+  button-primary-success:
+    backgroundColor: "{colors.success}"
+    textColor: "{colors.gray-00}"
+  button-primary-success-hover:
+    backgroundColor: "{colors.success-hover}"
+    textColor: "{colors.gray-20}"
+  button-primary-error:
+    backgroundColor: "{colors.error}"
+    textColor: "{colors.gray-00}"
+  button-primary-error-hover:
+    backgroundColor: "{colors.error-hover}"
+    textColor: "{colors.gray-20}"
+  button-primary-skyblue:
+    backgroundColor: "{colors.secondary-b2c}"
+    textColor: "{colors.gray-00}"
+  button-primary-skyblue-hover:
+    backgroundColor: "{colors.secondary-b2c-hover}"
+    textColor: "{colors.gray-00}"
+  button-secondary:
+    backgroundColor: transparent
+    textColor: "{colors.gray-80}"
+    borderColor: "{colors.gray-80}"
+    borderWidth: 2px
+    rounded: "{rounded.x8}"
+    typography: "{typography.button-2}"
+  button-secondary-hover:
+    backgroundColor: "{colors.gray-20}"
+    borderColor: "{colors.gray-60}"
+  button-secondary-skyblue:
+    backgroundColor: transparent
+    textColor: "{colors.secondary-b2c}"
+    borderColor: "{colors.secondary-b2c}"
+    borderWidth: 2px
+    rounded: "{rounded.x8}"
+  button-secondary-skyblue-hover:
+    backgroundColor: "{colors.secondary-lighter}"
+    borderColor: "{colors.secondary-b2c}"
+  button-tertiary:
+    backgroundColor: transparent
+    textColor: "{colors.gray-80}"
+    rounded: "{rounded.x8}"
+    typography: "{typography.button-2}"
+  button-size-small:
+    padding: "4px 16px"
+    gap: "{spacing.x2}"
+  button-size-medium:
+    padding: "12px 24px"
+    gap: "{spacing.x2}"
+  button-size-big:
+    padding: "16px 32px"
+    gap: "{spacing.x2}"
+  button-icon-only:
+    padding: "{spacing.zero}"
+    width: 32px
+    height: 32px
+---
+
+# CTC Component Library — Design System
+
+## Overview
+
+CTC is an educational platform with two surfaces: **B2B (institutions)** anchored in deep forest green, and **B2C (learners)** anchored in a brighter sky blue. The system is built atomic-style (atoms → molecules → organisms) on React 18 + TypeScript, with SCSS BEM as the styling layer and Ant Design 5 as a low-level primitive base. Tailwind 3 is loaded but intentionally unconfigured (no `theme.extend`) — it is used only for utility resets, not as a token source.
+
+The visual tone is **calm, literate, professional**. The serif display face (Roca One Light) gives headings an editorial feel, while a geometric sans (NT Bau) keeps body and UI copy efficient. The palette pairs muted neutrals with one saturated brand color per surface so that a single primary action is always unambiguous on screen.
+
+Token source of truth: `src/foundationTokens/*.scss` (consumed by all components via `@use`). The mirror under `src/commons/*.ts` is the public NPM export (`ctc-component-library/theme/{colors,shapes,spacing}`) — see _Do's and Don'ts_ for known TS↔SCSS drift.
+
+## Colors
+
+The palette is grouped into a 6-step neutral ramp, two brand families (B2B green, B2C blue), two accent families (purple, orange), and four status colors. Each brand and accent family is layered as `dark → default → light → lighter` to support emphasis and tonal backgrounds without shadows.
+
+- **Neutrals (`gray-100` `#171a1a` → `gray-00` `#fcfffe`):** Six-step ramp covering body text, UI chrome, dividers, surfaces, and disabled states. `gray-80` is the canonical body-text color; `gray-20` is the canonical disabled background; `gray-40` the canonical disabled text.
+- **Primary / B2B Green (`primary` `#1e5349`):** Identity color for institutional and B2B surfaces. `primary-light` `#6be3d7` is the default primary-button fill; `primary-lighter` `#daf2f0` is its hover.
+- **Secondary / B2C Blue:** Two parallel sub-palettes. `secondary` `#1d5bbc` (deep) is used for B2C headings and accents. `secondary-b2c` `#468eff` (sky) is the dedicated _skyblue_ button family for consumer flows, with `secondary-b2c-hover` `#84b2fb`.
+- **Purple (`purple` `#756dc8`):** Accent for non-status decorative emphasis (illustrations, secondary highlights).
+- **Orange (`orange` `#e57b43`):** Warm accent. Reserved for marketing surfaces and onboarding moments — not a status color.
+- **Status:** `error` `#c00808`, `success` `#206614`, `alert` `#9f760b`, each with a `-light` tonal background for inline messages and an `-hover` step where applicable.
+
+Opacity scale (`1, 0.8, 0.6, 0.4, 0.2`) is exposed in `src/commons/colors.ts` as `Opacidad100…Opacidad20` for use in overlays and disabled compositions; not surfaced in tokens above because it modulates any color rather than naming one.
+
+## Typography
+
+Two families, two roles:
+
+- **Roca One** (serif, weight 300 "Light") — every heading `h1`–`h5`. Larger sizes carry positive letter-spacing (1.5px → 0.6px) to keep the light weight readable. Files: `public/fonts/RocaOneLight.ttf`, `RocaOneRegular.ttf`.
+- **NT Bau** (geometric sans, weight 400 "Regular") — every body and button level. All non-display text uses a small **negative** `letter-spacing` (`-0.5px`) for tighter, denser running copy. Files: `public/fonts/NTBauRegular.otf`, `NTBauBold.otf`.
+
+The scale is opinionated: 5 heading levels, 6 body levels, 2 button levels. Bodies range 12px → 24px; defaults are `body-4` (16px) for paragraph copy, `body-5` (14px) for UI labels, `body-6` (12px) for metadata. Buttons use `button-2` (16px) at all sizes by default; `button-1` (18px) is reserved for the `big` button size when extra emphasis is desired.
+
+`bolder` is exposed as a Typography prop modifier — when on, it overrides the inherited weight rather than introducing a new typography token.
+
+## Layout
+
+A strict **4px base scale** drives every spacing and radius decision. The scale is keyed `x1`…`x20` where the number is the multiplier: `x1=4`, `x2=8`, `x4=16`, `x8=32`, `x20=80`. Token `zero` (`0px`) is provided for explicit zeroing in token-driven SCSS (`#{spacingTokens.$zero}`).
+
+There is no prescriptive grid — components are self-sized and composed by the host application. What the system does prescribe is rhythm:
+
+- **Default gap** between adjacent atoms: `spacing.x2` (8px).
+- **Component internal padding** is one of three steps: small (`4px / 16px`), medium (`12px / 24px`), big (`16px / 32px`) — see Button.
+- **Section-level spacing** typically uses `x6` (24px) and `x10` (40px).
+
+Tailwind is present but its theme is _not_ extended — do not rely on Tailwind utility classes for spacing/colors when authoring library components; consume the SCSS tokens instead.
+
+## Motion
+
+Animations follow Emil Kowalski's design engineering philosophy: every motion has a clear purpose, easings are custom (built-in CSS easings lack punch), durations stay under 300ms for UI, and only `transform`/`opacity` are animated (GPU, no layout/paint).
+
+**Custom easings** (defined in `theme.css`):
+- `--ease-out: cubic-bezier(0.23, 1, 0.32, 1)` — entrances, color transitions, hover. Starts fast for instant feedback.
+- `--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1)` — on-screen movement (drawer slides, layout shifts).
+- `--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1)` — iOS-like drawer curve.
+
+**Never `ease-in`** for UI — feels sluggish at the moment the user is watching most closely.
+
+**Duration scale** (token → use):
+- `--duration-instant: 100ms` — button press feedback.
+- `--duration-fast: 160ms` — color transitions, hover, small popovers.
+- `--duration-base: 200ms` — selects, dropdowns, popovers, tooltips.
+- `--duration-slow: 280ms` — modals, drawers.
+
+**Press feedback**: every pressable element scales to `--press-scale: 0.97` on `:active`. Implemented via `data-pressable` attribute or component-level `active:scale-[var(--press-scale)]`.
+
+**Stagger**: list items in selects/comboboxes/dropdowns reveal with `--stagger-step: 35ms` between siblings. Apply via `.ctc-stagger` utility class on the list container; first 12 children get auto delays.
+
+**Asymmetric timing**: enter animations are slightly slower than exits. A modal opens at 280ms but closes at 160ms — slow when the user is deciding, snappy when the system is responding.
+
+**Origin awareness**:
+- Popover/Tooltip/Select content scales from the trigger via Radix's `--radix-*-content-transform-origin` CSS variable.
+- Modals are the exception: `transform-origin: center` because they are not anchored to a specific trigger.
+
+**Reduced motion** (`prefers-reduced-motion: reduce`): all animations and transitions drop to 0.01ms; press scale is disabled. Opacity transitions are preserved for state comprehension.
+
+**Touch hover guard**: hover-only effects gate behind `@media (hover: hover) and (pointer: fine)` to avoid false positives on tap.
+
+**Per-component application**:
+
+| Component | Motion |
+|---|---|
+| Button | `:active scale(0.97)`, color/transform transitions 160ms ease-out, loading spinner 700ms linear |
+| Dialog | overlay fade 220ms ease-out, content scale 0.96 → 1 + opacity, **origin center**, exit 160ms |
+| Popover | scale 0.96 → 1 + opacity, origin Radix var, 200ms ease-out, exit 160ms |
+| Tooltip | scale 0.97 → 1, 125ms ease-out, origin Radix var, instant on subsequent hovers (Provider `skipDelayDuration: 200`) |
+| Select / Combobox / MultiSelect | trigger press scale, content scale 0.96 → 1 origin Radix var, **items stagger 35ms** with `ctc-fade-rise` (translateY(4px) → 0 + opacity), caret rotates 180° on open |
+| Tabs | trigger smooth color, **underline indicator slides via scaleX origin center**, content fades + rises 200ms ease-out on activation |
+| Toast | sonner default (Emil-approved) |
+| Switch | thumb translate 200ms ease-out, `:active scale(0.95)` |
+| Checkbox | indicator scale 0 → 1 enter, `:active scale(0.92)` |
+| RadioGroup | indicator scale 0 → 1 + opacity, `:active scale(0.92)` |
+| Avatar | image fade + rise on `data-state=loaded` |
+| Alert | enter `ctc-fade-rise` 200ms ease-out |
+| Spinner | spin 700ms linear (faster than Tailwind default; perceived performance) |
+| Input | border-color transition 160ms ease-out on focus/invalid |
+| NumberInput | stepper buttons `:active scale(0.85)`, color transition |
+| DatePicker | calendar reveals via Popover anim, day buttons `:active scale(0.92)` + smooth bg, trigger press feedback |
+| TimePicker | inherits Select |
+| DataTable | row bg transition 160ms ease-out, expand caret rotates 90°, sub-row `ctc-fade-rise` enter |
+| Field | invalid-state color transition 160ms ease-out |
+
+## Elevation & Depth
+
+The system is **flat**. Hierarchy is conveyed through:
+
+1. **Tonal contrast** — surfaces step through `gray-00 → gray-20 → gray-100`; raised content sits on a lighter neutral than its container.
+2. **Borders** — secondary buttons and inputs use 1–2px borders in `gray-80` or the relevant brand color, switching to `gray-40` when disabled.
+3. **Color emphasis** — a saturated brand fill (e.g. `primary-light`, `secondary-b2c`) is itself the elevation cue for a primary action.
+
+No `box-shadow` tokens are defined and components do not apply drop shadows. If a future surface needs a shadow (e.g. floating popover), introduce it as a new `elevation` token group rather than ad-hoc.
+
+## Shapes
+
+Radii share the same numeric scale as spacing (`x1=4` … `x20=80`) but are semantically about corner softness, not gap. The default for interactive containers (buttons, inputs) is `rounded.x8` (32px) — this is the system's signature, large enough to read as soft and friendly without becoming a pill at common widths. Cards and modals typically step down to `rounded.x4` (16px) or `rounded.x3` (12px). Avoid sharp (0px) corners and full-pill (`9999px`) radii — neither belongs to the language.
+
+## Components
+
+Atomic structure:
+
+- **Atoms:** `Avatar`, `Badge`, `Button` (+ `ButtonV2`), `Checkbox`, `Datepicker`, `Icon`, `InputNumber`, `Label`, `Popover`, `RadioButton`, `TextInput`, `Timepicker`, `Toast`, `Toggle`, `Typography`, `tooltips`.
+- **Molecules:** `Table`, `alert`, `dropdowns`, `tabs`.
+- **Organisms:** `Modal` (+ `ModalV2`).
+
+Author all new components with: `<Component>.tsx`, `<Component>.scss` (BEM, `@use` of foundation tokens), `types.ts`, `index.ts`, `<Component>.test.tsx`, optional `<Component>.stories.ts`. Re-export from `src/components/<layer>/index.ts`.
+
+### Button
+
+Three variants × three sizes × four primary color modes. Default radius `rounded.x8`. Default gap between icon and label `spacing.x2`. Icons are 24×24 from `@material-symbols/font-400` (`outlined` | `rounded` | `sharp`).
+
+| Token | Value |
+|---|---|
+| `button-primary` | green default — `{colors.primary-light}` on `{colors.gray-80}` |
+| `button-primary-neutral` | dark CTA — `{colors.gray-80}` on `{colors.gray-00}` |
+| `button-primary-success` / `-error` | semantic CTAs (status colors on `gray-00`) |
+| `button-primary-skyblue` | B2C primary — `{colors.secondary-b2c}` on `{colors.gray-00}` |
+| `button-secondary` | transparent fill, 2px `gray-80` border |
+| `button-secondary-skyblue` | transparent fill, 2px `secondary-b2c` border |
+| `button-tertiary` | text-only, no border, no fill |
+| `button-size-small` | padding `4px 16px` |
+| `button-size-medium` | padding `12px 24px` |
+| `button-size-big` | padding `16px 32px` |
+| `button-icon-only` | square 32×32, padding 0 |
+
+All variants share `rounded.x8` and `typography.button-2`. Disabled state across primary variants: `gray-20` background + `gray-40` text. Loading state spins an icon (1s linear infinite).
+
+### Input fields (`TextInput`, `InputNumber`, `Datepicker`, `Timepicker`)
+
+Borders in `gray-40` default → `gray-80` focus → `error` invalid. Use `body-5` for the value text and `body-6` for helper/error captions. Radius `rounded.x2` (8px) — tighter than buttons because inputs are read as containers, not actions.
+
+### Selection (`Checkbox`, `RadioButton`, `Toggle`)
+
+Selected state uses `primary` (B2B contexts) or `secondary-b2c` (B2C contexts). Focus ring uses the same color at 0.2 opacity. Labels in `body-5`.
+
+### Feedback (`Toast`, `alert`, `Badge`)
+
+Backgrounds use the `-light` step of a status color, text the `-main` step. Toasts use `body-5`; badges use `body-6`. Radius `rounded.x4` (16px) for toasts, `rounded.x8` for badges (pill-like).
+
+### Surface (`Modal`, `Popover`, `tooltips`)
+
+Modals: `gray-00` surface, `rounded.x4` corners, padding `x6` (24px). Popovers and tooltips: `gray-100` background with `gray-00` text, `rounded.x2`, padding `x2`/`x3`.
+
+### Composition (`Table`, `tabs`, `dropdowns`)
+
+Tables use 1px `gray-20` row dividers, header text in `body-6` uppercase. Tabs use `body-4` with a 2px `primary` (or `secondary-b2c`) bottom border on active. Dropdown menus use a `gray-00` surface with `rounded.x2` and items in `body-5`.
+
+## Do's and Don'ts
+
+- **Do** import token values from SCSS via `@use '../../../foundationTokens/{colors|shapes|spacing}.scss' as ...` — never hardcode hex or px in component styles.
+- **Do** name SCSS classes with BEM: `.block`, `.block__element`, `.block--modifier` (mirror the pattern in `Button.scss` / `ButtonV2.scss`).
+- **Do** keep all spacing and radii on the 4px scale (`x1`…`x20`). If a value isn't on the scale, you are probably solving the wrong problem.
+- **Do** pair each heading with `Roca One` and each body/UI string with `NT Bau`. Never the reverse.
+- **Do** render icons via `@material-symbols/font-400` at 24×24, with `iconType` `outlined | rounded | sharp` matching the surrounding component's tone.
+- **Do** ship a `dataTestid` prop on every interactive component for QA hooks.
+- **Don't** introduce drop shadows or blur-based elevation. The system is flat — convey depth with tonal contrast or borders instead.
+- **Don't** mix Tailwind utility classes for color or spacing into library components. Tailwind's theme is intentionally not extended; SCSS tokens are the source of truth.
+- **Don't** trust the public TS export (`src/commons/colors.ts`) blindly — there are known drifts vs. the SCSS source: `MainGreenLight` (TS `#6be3cd` vs SCSS `#6be3d7`), `SecondaryPurpleDefault` (TS `#c15cff` vs SCSS `#756dc8`), `MainBlueDefault` (TS `#468eff` vs SCSS `#1d5bbc`), `SuccessLight` (TS `#c15cff` vs SCSS `#e5ffea`). The values in this DESIGN.md follow the SCSS file, which is what components actually render.
+- **Don't** use `secondary-b2c` (sky blue) on B2B surfaces or `primary` (forest green) on B2C surfaces — the brand split is meaningful.
+- **Don't** introduce a fourth button variant or a new size step without updating both `Button.scss` and this file. The (3 variants × 3 sizes × 4 color modes) matrix is intentionally finite.