19 · Components

19 — Components

Versión: 0.1 Última actualización: 2026-04-24

Design system de componentes alineados con el brand identity. Cada componente rechaza explícitamente defaults de AI-template.

---

Principios de componentes

1. Función > decoración — cada elemento gana su lugar
2. Restraint — shadows sutiles, bordes definidos, transiciones calmadas
3. Texturas cálidas — subtle paper grain donde aporte
4. Typography-first — texto cuidado antes de container ornamental
5. Border > fill cuando sea posible — borders finos definen jerarquía

---

Containers

Card (estándar)

Para contenido agrupado (chapter preview, lesson card, etc.)

Dark mode:

bg: ink-2 (#24201a)
border: 1px border-warm (#3a2f25)
radius: 6px (NO 16px rounded pill)
padding: 20-24px
shadow: NONE (solo hover)
hover: border cambia a terracotta, shadow 0 2px 8px rgba(214,122,60,0.08)

Anatomía:

┌─────────────────────────────┐
│ [CH 01] [5 steps · 15 min]  │  ← meta row (Work Sans 12px uppercase)
│                             │
│ Chapter Title               │  ← Fraunces 22px
│                             │
│ Short description text that │  ← Work Sans 15px, text-secondary
│ gives context.              │
│                             │
│ ─────                       │  ← optional divider (border-warm)
│ [Action →]     [more →]     │  ← CTAs
└─────────────────────────────┘

Panel (featured)

Para hero sections dentro de pages.

bg: gradient sutil sobre ink con 3-5% tint de accent del chapter
border-left: 4px solid [chapter accent]  ← identidad visible
padding: 32-40px
typography: Fraunces grande para título, resto Work Sans

Divider

Simple:

border-top: 1px solid border-warm (#3a2f25)
margin: 32px 0

Con ornamento (para separar sections grandes — marginal):

1px line con símbolo central:
────── ✦ ──────
centered · color: text-muted · 12px

---

Buttons

Regla absoluta: NO rounded-full pills (tipo Linear). NO shadow floating. NO gradient fill. NO hover-scale.

Primary (CTA principal)

bg: terracotta (#d67a3c)
text: ink (#1a1511) — oscuro sobre cálido
padding: 10px 20px (compacto, no oversized)
radius: 6px
font: Work Sans 500 · 15px
hover: brightness 108%, nada más
active: brightness 95%
disabled: opacity 0.4

Secondary (outline)

bg: transparent
border: 1px solid añil (#6a7ab5)
text: añil
padding: same as primary
hover: background añil/10, text color stays

Ghost (minimal)

bg: transparent
text: text-primary
padding: 8px 12px
hover: bg ink-2, no border
used: navigation, tool menus

Icon button

size: 36x36px
bg: transparent
icon: 16-20px
hover: bg ink-2, scale: none (NO scale 1.1)

---

Form elements

Input (text)

bg: ink-3 (#2f2a22)
border: 1px solid border-warm
radius: 4px (más cuadrado que buttons — inputs son más formales)
padding: 10px 14px
font: Work Sans 15px
text: text-primary
placeholder: text-muted

focus: border-color terracotta, no glow/ring (ring-0)
error: border-color oxblood, helper text oxblood below

Checkbox

16x16px
bg: ink-3
border: 1px border-warm (unchecked)
bg-checked: terracotta
check mark: ink color

NOT rounded-full pill toggles — actual squares con check marks

Select / Dropdown

same as input, + chevron de la paleta
dropdown panel: bg ink-2, border-warm, subtle shadow
item hover: bg ink-3
item active: bg terracotta/10 border-left terracotta 2px

---

Navigation

Top bar

Anatomía:

┌────────────────────────────────────────────────┐
│  Academia Agentes      Home  Catálogo  Docs   │
│  ───                                           │ ← subtle bottom line
└────────────────────────────────────────────────┘

Specs:

bg: ink con 95% opacity + backdrop-blur-sm (subtle, NOT glassmorphism)
border-bottom: 1px border-warm
padding: 12px 24px
height: 56px
logo: Fraunces 18px 600, terracotta accent color
nav items: Work Sans 15px, text-secondary, hover → text-primary
active item: text-primary, border-bottom 2px terracotta (inline)

Chapter tabs (within lesson)

Horizontal scroll con themed accents:

bg: ink-2 con backdrop-blur
tab inactive: bg-neutral-800/50, text-muted, 12px
tab current: bg [chapter-theme-accent], text ink
tab completed: bg ink-3, text-secondary, prefix ✓
gap between: 8px
padding per tab: 6px 12px
radius: 4px

Progress bar

Regla: progress bars son CRUCIALES para engagement. No escondidos.

height: 4-6px (visible)
bg (track): ink-3
bg (filled): terracotta o gradient sutil terracotta → cempazúchil
transition: width 300-500ms ease-out

---

Audio player (StepAudioPlayer)

Anatomía crucial — sticky top para siempre visible:

┌────────────────────────────────────────────────┐
│  [▶]  🔴 Narrando...          0:12 / 0:45  [↺] │  ← controls (siempre)
│  ━━━━━━━━━━━━━━━━━━────────────────────────    │  ← progress visible
│                                                 │
│  Karaoke captions paragraph...                 │  ← text below
│  past words bright, current violet/terracotta, │
│  future words dimmed.                           │
└────────────────────────────────────────────────┘

bg: ink-2
border: 1px terracotta/50 (brand accent, NOT violet)
play button: terracotta circle, 36-40px, pulse while playing
status label: Work Sans 500 uppercase 11px
  - playing: terracotta
  - ended: nopal (green)
  - blocked: cempazúchil (yellow)
progress track: ink-3
progress fill: terracotta
time display: JetBrains Mono 12px text-muted

Karaoke word states:

• Future: text-muted (#8a7a6a)
• Current: terracotta (#d67a3c) bold + slight scale(1.03)
• Past: text-primary (#f4ecdf) normal

---

Visual renderers (chapter internals)

ScreenshotTerminal

Keep current chrome style BUT adjust colors:

outer bg: ink (#1a1511) con slight inner shadow
chrome bar: ink-2 con macOS dots NOT in Apple exact colors — use ours:
  red: oxblood
  yellow: cempazúchil
  green: nopal
body font: JetBrains Mono 13px
prompt color: terracotta
command color: text-primary
output: text-secondary
caption: Work Sans 12px italic below, text-muted

ScreenshotEditor

chrome bar: ink-2 con file tab highlighted en terracotta border-bottom
file path: JetBrains Mono 12px text-secondary
line numbers: text-muted
code: JetBrains Mono 13px text-primary
highlight line bg: terracotta/15 (NOT violet)
annotation arrow + text: añil

DiagramStages

Container:

bg: ink-2 with paper texture SVG overlay (very subtle, 3-5% opacity)
border: 1px border-warm
padding: 20px (tighter than before)
svg container: min-height 150px (no 200+), responsive
caption: Work Sans 13px text-secondary center
stage dots: ink-3 default, terracotta current, hover text-secondary

Mini Quiz

bg: ink-2
border: 1px border-warm
padding: 20-24px

question: Fraunces 18px 600 text-primary
option default: bg ink-3, border border-warm, text text-primary
option hover: border terracotta/50
option selected: bg terracotta/10, border terracotta
option correct revealed: bg nopal/20, border nopal, check mark nopal
option wrong revealed: bg oxblood/20, border oxblood, x mark oxblood
explanation: bg ink-3 inset, text-secondary, sm

---

Code blocks (inline y block)

Inline code (en prosa)

bg: ink-3
padding: 2px 6px
radius: 3px
font: JetBrains Mono 0.9em (ligeramente smaller que body)
color: terracotta o cempazúchil (accent)

Block code (código largo)

bg: ink-3 oscuro (maybe even darker, #1a1410)
border: 1px border-warm
radius: 6px
padding: 16px 20px
copy button: top-right ghost button, tiny

syntax highlighting theme: Tokyo Night Warm o One Light (warm side)
NEVER Dracula (too cool) ni Cobalt (too saturated)

---

Badges / tags

bg: ink-3
text: text-secondary
padding: 3px 8px
radius: 3px (NOT pill!)
font: Work Sans 500 11px uppercase letter-spacing 0.06em

variants:
- default: text-secondary on ink-3
- accent: [color]/15 bg, [color] text, [color]/30 border
  (used for chapter lane: terracotta for Builder, añil for Operator, etc.)

---

Shadow scale

Very restrained. NO floating pills.

shadow-sm: 0 1px 2px rgba(0,0,0,0.2)       → card hover
shadow: 0 2px 8px rgba(0,0,0,0.25)         → dropdowns, popovers
shadow-md: 0 4px 16px rgba(0,0,0,0.3)      → modals (rare)
shadow-lg: 0 8px 32px rgba(0,0,0,0.4)      → very rare, hero elements

Los accents NEVER glow with shadow-[color]-500/50. Si hay resalte, es con borde, no con glow.

---

Animation principles

• Fast & purposeful: 120-250ms para feedback, 300-500ms para layout changes
• Easing: ease-out para entries, ease-in-out para two-way
• Scale animations: 1.0 → 1.02 max (no 1.1 bouncy)
• NOanimate-pulse en todo — solo para estados activos (live recording, loading)
• Respect prefers-reduced-motion — todas las transitions se desactivan

---

Dark mode vs Light mode

Default es dark mode warm. Light mode eventual toggle:

html[data-theme="light"] {
  /* palette flip */
  --bg: var(--color-paper);
  --text: var(--color-ink);
  /* ... */
}

Regla: NUNCA asumir que el user está en uno u otro — usa tokens, no hex directo.

---

Responsive behavior

Mobile-first obligatorio. Tablet (768+) → añade comodidades. Desktop (1024+) → layout expandido.

• Tipografía: reducir 1-2 steps en mobile
• Padding containers: reducir 30-40%
• Tabs: scroll horizontal, NO se envuelven a 2 líneas
• Cards: stack vertical en mobile, grid en tablet+
• Sidebar: hidden en mobile, drawer via menu

---

Anti-patterns UI

Lo que nuestro design system EXPLÍCITAMENTE evita:

• ❌ Glassmorphism: backdrop-blur-lg con bg-white/10
• ❌ Rounded-full pills para buttons y badges
• ❌ Bento grids con 8 cards de sizes diferentes
• ❌ Gradient fills en cards (bg-gradient-to-br)
• ❌ Shadow glows con color (shadow-[color]-500/50)
• ❌ Animate pulse en todos los loading states
• ❌ Borders coloridos con rounded-2xl (tipo cards AI marketing pages)
• ❌ Emoji grandes como decoración (emoji ≤ 1em, inline)
• ❌ Hover-scale-105 transitions
• ❌ Tooltips con animate-bounce
• ❌ Frosted glass modals