LRP Design System

Single source of truth for all visual decisions in the LRP application. Built on the W3C DTCG standard — tool-agnostic, version-controlled, and ready for AI-assisted development.

Current version: v0.2.3

What This Repo Is

This repo contains design tokens — named design decisions stored in JSON files. One change here propagates to all consumers (Angular, React, Vue, Figma, Lovable, Tailwind). In Angular: add dist/tokens.css to angular.json styles, then run npm run tokens:build to regenerate after any token change. Changes propagate via CSS custom properties. A DESIGN.md file is also generated on every build for AI tools.

tokens/*.json (source of truth)
        ↓
Style Dictionary (npm run tokens:build)
    ↙           ↓           ↘         ↘
dist/tokens.css  dist/_tokens.scss  dist/tokens.json  DESIGN.md
    ↓                ↓                    ↓               ↓
Angular CSS vars  Angular SCSS       Figma · Tailwind  AI tools

No tool owns the truth. The JSON files do.

⚠️ Critical: For changes to reach any consumer, the build step must run in your CI/CD pipeline. dist/tokens.css is generated by Style Dictionary, not hand-written. Without npm run tokens:build, the pipeline will fail because dist/tokens.css does not exist.

Quick Start

From npm (recommended for consumers)

# Install the package
npm install @logit/lrp-design-system

# Load CSS variables globally in angular.json
"styles": [
  "node_modules/@logit/lrp-design-system/dist/tokens.css",
  "src/styles/main.scss"
]

From source (for contributors)

# Clone the repository
git clone https://bitbucket.org/magnum_col/lrp-design-system.git
cd lrp-design-system

# Install dependencies
npm install

# Build all token outputs (CSS, SCSS, JSON, DESIGN.md)
npm run tokens:build

# Watch for changes during development
npm run tokens:watch

Outputs:

| File | Use | |---|---| | dist/tokens.css | Load globally in Angular via angular.json styles array | | dist/_tokens.scss | Import in styles.scss for backward-compat SCSS migration | | dist/tokens.json | Feed to Figma (Tokens Studio), Tailwind config, or AI context | | DESIGN.md | Auto-generated machine-readable design spec for AI tools |

Using in Angular

1. Load CSS variables globally

In angular.json, add to the styles array:

"styles": [
  "path/to/lrp-design-system/dist/tokens.css",
  "src/styles/main.scss"
]

This makes every CSS custom property available in every component — zero imports needed.

2. Use tokens in component stylesheets

// button.component.scss
.button--primary {
  background:    var(--button-primary-bg);
  color:         var(--color-text-inverse);
  padding:       var(--spacing-base) var(--spacing-base);
  border-radius: var(--button-primary-radius);
  transition:    var(--motion-fast);

  &:hover         { background: var(--button-primary-bg-hover); }
  &:focus-visible { outline: 2px solid var(--color-border-focus); outline-offset: 2px; }
}

Rule: Never hardcode a hex color or pixel value in a component stylesheet. background: #1240b2 is a bug. background: var(--color-brand-default) is correct.

Token Architecture

Three tiers. Each has a single job.

Tier 1 — Primitive

Folder: tokens/primitive/ Job: The full palette of available values. No meaning attached.

// tokens/primitive/color.json
"color": {
  "blue": {
    "700": { "$value": "#1240b2", "$type": "color" }
  }
}

Tier 2 — Semantic

Folder: tokens/semantic/ Job: What values are for. Every token answers a purpose question.

// tokens/semantic/color.json
"color": {
  "brand": {
    "default": {
      "$value": "{color.blue.700}",
      "$type": "color",
      "$description": "Primary brand. CTAs, active nav, key interactive affordances."
    }
  }
}

Tier 3 — Component

Folder: tokens/component/ Job: How a specific component uses the system.

// tokens/component/button.json
"button": {
  "primary": {
    "bg": { "$value": "{color.brand.default}" }
  }
}

The rule: Components reference semantic. Semantic references primitive. Components never skip a tier.

Current token coverage

| Category | Primitive tokens | Semantic tokens | Component tokens | |---|---|---|---| | Color | 50+ (gray, blue, green, red, yellow, alpha) | brand, bg, text, border, status, overlay | button, form-field, table, card, modal, badge, nav, toast, tooltip | | Spacing | 13 steps (4px → 64px) | 8 named roles | button, form-field | | Typography | family, 6 sizes, 5 weights | 6 named roles | button, form-field, badge | | Border radius | 6 steps | 6 named roles | button, form-field, card, modal, badge, nav, toast | | Shadow | 3 elevations | card, panel, modal, focus | modal, toast | | Motion | 6 durations, 4 easings | 5 named presets | button, form-field, modal, toast | | Z-index | 6 layers | 6 named layers | modal, nav, toast | | Breakpoints | 6 steps (480px → 1600px) | — | — |

Token Naming

Structure: [category].[concept].[variant].[state]

color.brand.default          ← semantic color
color.bg.page                ← semantic background
button.primary.bg            ← component token
button.primary.bg-hover      ← component token with state

Standard states (always in this order): default → hover → active → focus → disabled → loading

See docs/naming-conventions.md for the full vocabulary.

Repository Structure

lrp-design-system/
├── README.md                    ← this file
├── DESIGN.md                    ← auto-generated visual identity spec for AI tools (never edit manually)
├── DESIGN_DECISIONS.md          ← the "why" behind every decision (for AI context too)
├── CHANGELOG.md                 ← SemVer token change log
├── package.json                 ← style-dictionary v4 + scripts
├── sd.config.js                 ← Style Dictionary configuration
├── scripts/
│   └── generate-design-md.mjs  ← generates DESIGN.md from dist/tokens.json
│
├── tokens/
│   ├── primitive/               ← raw values (color, spacing, type, radius, shadow, motion, z, breakpoint)
│   ├── semantic/                ← intent layer (brand, bg, text, border, spacing roles, etc.)
│   └── component/               ← component-scoped decisions (button, form-field, table, etc.)
│
├── dist/                        ← generated outputs (run npm run tokens:build)
│   ├── tokens.css               ← CSS custom properties
│   ├── _tokens.scss             ← SCSS variables
│   └── tokens.json              ← flat JSON map
│
└── docs/
    ├── naming-conventions.md    ← token taxonomy and rules
    ├── contributing.md          ← how to add/change tokens + PR checklist
    ├── guidelines.md            ← UI behavior rules (table alignment, forms, buttons, modals)
    ├── migration-status.md      ← frontend migration debt tracker (delete after Phase 4)
    ├── migration.md             ← old SCSS variable → new token mapping
    ├── how-it-works.md          ← architecture explained from first principles
    └── slides/
        └── design-system-presentation.html  ← interactive presentation (open in browser)

Documentation

| Document | What it covers | |---|---| | DESIGN.md | Auto-generated machine-readable spec (YAML tokens + prose rationale). Feed to AI tools like Claude Code or Lovable when generating LRP components. Never edit manually — regenerated on every build. | | DESIGN_DECISIONS.md | The "why" behind color, spacing, type, radius, motion, and accessibility rules. Read before adding or modifying tokens. | | docs/guidelines.md | UI behavior rules — table alignment, form patterns, button hierarchy, modals, toasts, empty states. | | docs/how-it-works.md | Architecture from first principles — the chaos, the build, the consumers, the agent layer. | | docs/naming-conventions.md | Token taxonomy, category vocabulary, and anti-patterns. | | docs/contributing.md | How to add/modify tokens, the deprecation pattern, PR checklist. | | docs/migration.md | Maps every old _variables.scss variable to its new token equivalent. Use during component migration. | | docs/migration-status.md | Live tracker of hardcoded values still to be migrated in lrp_frontend. Delete after Phase 4 is complete. |

AI Usage

When asking an AI tool (Claude Code, Lovable, Copilot) to generate LRP components, include:

1. DESIGN.md — the visual identity spec (auto-generated, always current)
2. DESIGN_DECISIONS.md — the rationale behind every decision
3. docs/guidelines.md — UI behavior rules

The /ds-health skill (.claude/skills/ds-health/) runs a build + lint check after token changes to catch broken references and WCAG violations before they reach lrp_frontend.

Figma Integration (Tokens Studio)

1. Install Tokens Studio (free plugin) in Figma
2. Connect to this repo with a GitHub Personal Access Token (repo scope)
3. Point to the tokens/ folder — it reads DTCG JSON automatically
4. Sync creates Figma Variables that mirror the three-tier structure

Figma is a consumer, not the source. The JSON files are the source of truth. Treat Figma Variables the same way you treat the generated CSS — both are downstream outputs.

Publishing to npm

Prerequisites

1. Have an npm account at https://www.npmjs.com/signup
2. Login to npm:

   npm login

Publishing

Use the provided script for automated version bump and publish:

# Patch version (0.1.0 → 0.1.1) - bug fixes
bash scripts/publish.sh patch

# Minor version (0.1.0 → 0.2.0) - new features
bash scripts/publish.sh minor

# Major version (0.1.0 → 1.0.0) - breaking changes
bash scripts/publish.sh major

Or manually:

# Bump version
npm version patch  # or minor, or major

# Publish to npm
npm publish

The package will be available at: https://www.npmjs.com/package/@logit/lrp-design-system

Workflow for Publishing

1. Create a feature branch for the changes:

   git checkout -b features/despliegue-npm

2. Make changes to tokens, scripts, or configuration

3. Build tokens to validate changes:

   npm run tokens:build

4. Commit changes:

   git add .
   git commit -m "feat: descripción del cambio"

5. Push branch to Bitbucket:

   git push origin features/despliegue-npm

6. Create Pull Request in Bitbucket:

   • Go to https://bitbucket.org/magnum_col/lrp-design-system/pull-requests
   • Create PR from features/despliegue-npm to main
   • Request review from team members

7. After PR is merged to main:

   git checkout main
   git pull origin main
   npm version patch  # or minor, or major
   npm publish

Versioning

This system follows Semantic Versioning:

| Change | Bump | |---|---| | Rename or remove a token (breaking) | MAJOR | | Add a new token | MINOR | | Fix a value, improve a description | PATCH |

See CHANGELOG.md for the full history.

Standards

Built on:

• W3C DTCG Format — the open standard adopted by Figma, Tokens Studio, Style Dictionary
• Style Dictionary v4 — Amazon's open-source token transform pipeline
• Semantic Versioning
• DESIGN.md format — Google Labs machine-readable design spec

Compatible with: Angular, React, Vue, Svelte, Figma, Lovable, Tailwind, and any tool that reads CSS or JSON.