# Transmodal Design System

A reusable Open Design package for Grupo Transmodal — Mexican multimodal logistics and transport operator. This is the canonical source for color, typography, spacing, components, and brand assets used across Transmodal's commercial landing pages, sales proposals, slide decks, and operations dashboards.

`DESIGN.md` is the canonical rules document. This README is the orientation guide for agents and humans starting new Transmodal projects from the package.

## Product Overview

**Who.** Grupo Transmodal — a Mexican logistics operator running multimodal (sea + land + rail) freight along the Pacific corridor (Lázaro Cárdenas, Manzanillo) and the cross-border Texas–Monterrey lane. This package provides the visual platform every Transmodal client-facing and internal tool is built on, and it supports the four primary product surfaces below.

**What we build with this system.** The primary UI surfaces this package powers:

- **Commercial landing pages** — public-facing marketing pages that describe coverage, services, and lead-generation forms for shippers requesting cotizaciones.
- **Sales proposals & slide decks** — 1920×1080 decks for enterprise pitches and operating reviews.
- **Operations dashboards** — internal dispatcher consoles for tracking embarques in tránsito, customs status, and patio activity.
- **Customer portals** — shipment tracking, document download (BL, pedimento), and account reporting for shippers.
- **Brand collateral** — social posts, BOOMS (campaign visuals), and operational photography templates.

**Core capabilities the system encodes.** Operator-grade reliability and density (tabular numerics, customs steppers, real status pills), brand-led restraint (one accent — lime — reserved for CTA and on-time signals), and Spanish-first operator voice (`embarque`, `unidad`, `pedimento`, never marketing fluff).

**Source basis.** Brand wordmarks (`logo-grupo-transmodal-azul.png`, `logo-grupo-transmodal-blanco.png`), institutional photography (`transmodal-team-photo.png` — origin of the tagline *"Protege lo tuyo"* and the lime accent), the official DM Sans typeface bundle (`DM_Sans.zip`), the locally-parsed Figma summary in `context/figma/transmodal---design-system.md`, and the operator-context brief captured in `context/source-context.md`.

## Source References

| Source | Location | Use |
|---|---|---|
| Brand wordmarks | `assets/logo-grupo-transmodal-azul.png`, `assets/logo-grupo-transmodal-blanco.png` | Canonical marks. Do not redraw or recolor. |
| Institutional photo | `assets/transmodal-team-photo.png` | Reference for hero composition and tagline lockup. |
| Brand typeface | `fonts/DMSans-*.ttf` + `assets/DM_Sans.zip` | DM Sans bound through `@font-face` in `colors_and_type.css`. |
| Runtime icons | `build/icon.png`, `build/logo.png`, `build/logo-dark.png`, `build/tray_icon.png` | App icon, runtime brand logo (light + dark), tray icon. Preserved byte-for-byte from the source uploads. |
| Figma source summary | `context/figma/transmodal---design-system.md` | Local parse of `Transmodal - Design System.fig` (binary; no readable token text surfaced). |
| Setup brief | `context/source-context.md` | Operator brief, brand asset list, review contract. |
| Reference components | `source_examples/*.jsx` | Standalone copies of the highest-signal product modules. |

## Package contents

```
ds-transmodal-design-system/
├── README.md                    ← this file
├── SKILL.md                     ← Claude-style agent-usable skill entry
├── DESIGN.md                    ← canonical rules (color, type, spacing, components, motion, voice)
├── colors_and_type.css          ← tokens + @font-face bindings + button/input/pill primitives
├── assets/                      ← brand wordmarks, team photo, DM Sans bundle
├── build/                       ← runtime icons preserved with original filenames
├── fonts/                       ← DM Sans TTF files + OFL license
├── context/                     ← evidence preserved from setup (source-context.md, Figma summary)
├── preview/                     ← reviewable HTML cards for the visual system
├── source_examples/             ← standalone reference components (Sidebar, ShipmentsList, …)
└── ui_kits/app/                 ← applied ops dashboard kit (React + Babel via index.html)
```

## Preview Manifest

Every card mounts the production `colors_and_type.css` directly so the previews are tokens-true. Open them through the Open Design `Design System` tab or as plain files.

| Path | What reviewers should inspect | Source-backed elements |
|---|---|---|
| `preview/index.html` | The index of all preview cards. | Layout + tx-* helper classes from `colors_and_type.css`. |
| `preview/colors-primary.html` | Brand scale + state tokens — token names, hex values, intended use, AA-safe lime pairing. | `--brand-navy-{900,800,700}`, `--brand-blue-{600,500,300}`, `--brand-cyan-400`, `--brand-lime-{500,700}`, all state tokens. |
| `preview/colors-theme-light.html` | The default theme for sales/landing surfaces. Neutral surfaces, hero block, and pills in context. | `--bg`, `--surface`, `--surface-2`, `--fg`, `--muted`, `--border`, all `.pill-*` variants. |
| `preview/colors-theme-dark.html` | The dispatcher canvas. Navy surfaces, KPI tiles, ops pills. Renders with `data-theme="dark"`. | Dark-theme override block in `colors_and_type.css`; KPI typography helpers (`.tx-num`, `--type-h1`). |
| `preview/typography-specimens.html` | Full type scale rendered with DM Sans bound from `fonts/`. Display, headings, body, caption, mono. | `--font-sans`, `--font-mono`, `--type-*`, six DM Sans weights/styles, tabular numerics. |
| `preview/spacing-tokens.html` | 8-pt spacing ladder (4px → 128px) shown to scale. | `--space-1` through `--space-10`. |
| `preview/spacing-radius.html` | Four corner radii plus the pill radius used only by status badges. | `--radius-sm/md/lg/xl/pill`. |
| `preview/spacing-shadows.html` | Three-step elevation ladder, tinted navy. | `--shadow-1/2/3`. |
| `preview/components-buttons.html` | Primary (lime CTA), Secondary (navy), Ghost, Destructive — including disabled state and a dark-surface variant. | `.btn-*` classes from `colors_and_type.css`. |
| `preview/components-inputs.html` | Form fields (input, select, textarea, RFC error state) + status pills + the five-step customs stepper. | `.input`, `[aria-invalid="true"]` styling, `.pill-*` variants, custom stepper pattern from DESIGN.md §6. |
| `preview/brand-assets.html` | Real wordmark files on light and dark stages, runtime icons from `build/`, and the institutional photo loaded as the hero. | Direct `<img>` references to `assets/logo-grupo-transmodal-{azul,blanco}.png`, `assets/transmodal-team-photo.png`, and `build/{icon,logo,logo-dark,tray_icon}.png`. |

## Reuse workflow

1. **Read** `DESIGN.md` before generating anything Transmodal-branded. Sections 2 and 3 are the canonical color and type contracts.
2. **Bind** `colors_and_type.css` as the first stylesheet in every Transmodal project. It registers DM Sans through `@font-face` and exposes every token under `:root` and `[data-theme="dark"]`.
3. **Pick a theme.** Marketing, sales, and customer portals run in the default light theme; operations consoles and dispatcher tools run in dark mode (`data-theme="dark"`).
4. **Reuse components** from `ui_kits/app/components/` or `source_examples/`. Do not redefine `.btn`, `.input`, `.card`, or `.pill` — extend them.
5. **Use real brand assets.** Wordmarks come from `assets/`, runtime icons from `build/`. Do not redraw, recolor outside the two supplied variants, or substitute stock logos.
6. **Audit before publishing.** Run `"$OD_NODE_BIN" "$OD_BIN" tools connectors design-system-package-audit --path . --fail-on-warnings` from the project root and fix every reported issue.

Drafts cannot be consumed by other projects until the design system is published from Open Design.