@tramo-digital/styles

Modern PostCSS style library with dynamic design token integration. Framework-agnostic, modular, and built on the Open Design System token system.

Key Features

• Design Token Integration - Built on Open Design System token system (Global → Semantic → Appearance → States)
• PostCSS Powered - Modern CSS with imports, nesting, mixins, and custom media queries
• Light/Dark Mode - Automatic theme switching via CSS classes
• Responsive Design - Mobile-first breakpoint system (374px, 768px, 1440px)
• Modular Architecture - Import only what you need
• Framework Agnostic - React, Vue, Angular, vanilla CSS
• Zero Runtime - Pure CSS, no JavaScript required
• Fully Customizable - Override any token or style

Quick Start

Installation

npm install @tramo-digital/styles
# or
pnpm add @tramo-digital/styles

Basic Usage

Import Complete Library

/* Import everything (compiled CSS) */
@import '@tramo-digital/styles';

Import Source CSS with PostCSS

/* Import source CSS for PostCSS processing */
@import '@tramo-digital/styles/src';

/* Or import specific layers */
@import '@tramo-digital/styles/tokens';
@import '@tramo-digital/styles/base';
@import '@tramo-digital/styles/components/buttons';
@import '@tramo-digital/styles/utilities';

Use PostCSS Mixins

@import '@tramo-digital/styles/mixins';

.my-button {
  @mixin button-primary;
  @mixin button-lg;
}

.my-container {
  @mixin container;
}

Vanilla HTML

<link rel="stylesheet" href="node_modules/@tramo-digital/styles/dist/main.min.css">

Module Exports

| Export Path | Description | Type | |------------|-------------|------| | @tramo-digital/styles | Complete compiled library | CSS | | @tramo-digital/styles/css/min | Minified compiled library | CSS | | @tramo-digital/styles/src | Source CSS (requires PostCSS) | CSS | | @tramo-digital/styles/tokens | Design tokens only | CSS | | @tramo-digital/styles/mixins | PostCSS mixins | CSS | | @tramo-digital/styles/base | Reset styles | CSS | | @tramo-digital/styles/base/typography | Typography utilities | CSS | | @tramo-digital/styles/base/colors | Color utilities | CSS | | @tramo-digital/styles/components/buttons | Button components | CSS | | @tramo-digital/styles/components/forms | Form components | CSS | | @tramo-digital/styles/components/cards | Card components | CSS | | @tramo-digital/styles/layout/grid | Grid system | CSS | | @tramo-digital/styles/layout/flexbox | Flexbox utilities | CSS | | @tramo-digital/styles/utilities | Utility classes | CSS |

Design Token System

Token Hierarchy

Reference → Global → Semantic → Primitive → Pattern → Composition → Appearance → States → Themes

Using Tokens

Tokens are available as CSS custom properties:

/* Global tokens */
.element {
  padding: var(--global-spacing-16);
  border-radius: var(--global-border-radius-8);
  color: var(--color-swatch-brand-01);
}

/* Semantic tokens */
.card {
  background: var(--semantic-background-color-primary);
  color: var(--semantic-typography-color-text-body);
  border: 1px solid var(--semantic-border-color-primary);
}

/* Breakpoint tokens (responsive) */
.heading {
  font-size: var(--breakpoint-font-size-text-heading-lg);
}

/* Interactive state tokens */
.button {
  background: var(--states-interactive-button-primary-fill);
}

.button:hover {
  background: var(--states-interactive-button-primary-fill-hover);
}

Component Examples

Buttons

<button class="btn btn-primary btn-md">Primary Button</button>
<button class="btn btn-secondary btn-lg">Secondary Button</button>
<button class="btn btn-tertiary btn-sm">Tertiary Button</button>

Forms

<div class="form-group">
  <label class="label">Email</label>
  <input type="email" class="input" placeholder="Enter email">
  <span class="helper-text">We'll never share your email.</span>
</div>

Grid Layout

<div class="grid-container">
  <div class="col-span-12 md:col-span-6 lg:col-span-4">Column 1</div>
  <div class="col-span-12 md:col-span-6 lg:col-span-4">Column 2</div>
  <div class="col-span-12 md:col-span-6 lg:col-span-4">Column 3</div>
</div>

PostCSS Mixins

Available Mixins

/* Responsive breakpoints */
@mixin breakpoint-sm { /* 374px+ */ }
@mixin breakpoint-md { /* 768px+ */ }
@mixin breakpoint-lg { /* 1440px+ */ }

/* Button variants */
@mixin button-base;
@mixin button-primary;
@mixin button-secondary;
@mixin button-tertiary;

/* Button sizes */
@mixin button-sm;
@mixin button-md;
@mixin button-lg;

/* Layout */
@mixin container;
@mixin card;

/* Utilities */
@mixin focus-ring;
@mixin visually-hidden;
@mixin truncate;
@mixin clearfix;

Usage Example

@import '@tramo-digital/styles/mixins';

.custom-button {
  @mixin button-base;
  background: var(--color-swatch-brand-01);
  
  &:hover {
    background: var(--color-swatch-brand-03);
  }
  
  @media (--md) {
    @mixin button-lg;
  }
}

🌓 Themes

Light/Dark Mode

<!-- Light theme (default) -->
<body class="light">
  <!-- Your content -->
</body>

<!-- Dark theme -->
<body class="dark">
  <!-- Your content -->
</body>

<!-- Auto theme (follows system preference) -->
<body data-theme="auto">
  <!-- Your content -->
</body>

📱 Responsive Breakpoints

/* Custom media queries available */
@media (--sm)  { /* 374px+ (mobile) */ }
@media (--md)  { /* 768px+ (tablet) */ }
@media (--lg)  { /* 1440px+ (desktop) */ }

/* Or use utility classes */
.hidden { display: none; }
.md\:block { display: block; } /* Shows at 768px+ */
.lg\:flex { display: flex; } /* Shows at 1440px+ */

🎯 Utility Classes

Spacing

.p-16 { padding: 16px; }
.px-24 { padding-left: 24px; padding-right: 24px; }
.py-32 { padding-top: 32px; padding-bottom: 32px; }
.m-auto { margin: auto; }
.mb-16 { margin-bottom: 16px; }

Flexbox

.flex { display: flex; }
.flex-col { flex-direction: column; }
.items-center { align-items: center; }
.justify-between { justify-content: space-between; }
.gap-16 { gap: 16px; }

Typography

.text-heading-xl { /* Large heading */ }
.text-body-md { /* Body text */ }
.font-bold { font-weight: 700; }
.text-center { text-align: center; }

🛠️ PostCSS Configuration

If using source CSS, ensure PostCSS is configured with required plugins:

// postcss.config.js
export default {
  plugins: {
    'postcss-import': {},
    'postcss-mixins': {},
    'postcss-nested': {},
    'postcss-custom-media': {},
    'postcss-custom-properties': { preserve: true },
    'autoprefixer': {}
  }
}

🔧 Requirements

• Node.js >= 18.0.0
• PostCSS >= 8.4.0 (if using source CSS)

📚 Architecture

The library is organized with CSS Cascade Layers so token-driven styles compose predictably across frameworks:

• @layer tokens – generated design tokens from tui-tokens
• @layer base – resets, typography, foundational utilities
• @layer layout – grid, containers, flex helpers
• @layer components – scaffolded component patterns (buttons, forms, cards)
• @layer utilities – single-purpose helpers for rapid prototyping
• @layer themes – light/dark/auto theming hooks and accessibility adjustments

Because the layering order is declared in src/main.css, component libraries can safely override lower layers without duplicating CSS.

Layer Structure

src/
├── main.css                    # Entry point
├── tui-tokens/                 # Design tokens
│   ├── main.css              # Token imports (layered)
│   ├── reference/             # Global tokens
│   ├── semantic/              # Contextual tokens
│   ├── appearance-*/          # Visual tokens
│   └── color-palette/         # Theme tokens
├── abstracts/
│   └── mixins.css             # PostCSS mixins
├── base/                       # Base styles
│   ├── reset.css
│   ├── typography.css
│   ├── colors.css
│   └── utilities.css
├── layout/                     # Layout systems
│   ├── grid.css
│   ├── containers.css
│   └── flexbox.css
├── components/                 # Components
│   ├── buttons.css
│   ├── forms.css
│   └── cards.css
├── utilities/                  # Utility classes
│   ├── spacing.css
│   ├── sizing.css
│   ├── borders.css
│   ├── display.css
│   └── text.css
└── themes/                     # Themes
    ├── light.css
    ├── dark.css
    └── utilities.css

🤝 Integration with Open Design System

This library is part of the Open Design System design system:

• Tokens Source: @tramo-digital/core/designtokens
• Component Library: Works with @tramo-digital/react-ui, tramo-digital/vue-ui, etc.
• Build System: Nx monorepo

🔄 Updates

To update design tokens:

nx run @tramo-digital/styles:tokens-update

📖 Examples

See examples/ directory for:

• Basic usage patterns
• React component integration
• Vue component integration
• Custom PostCSS configuration

🤝 Contributing

See the [main repository](https://github.com/Open Design System/tramo-digital-main) for contribution guidelines.

📄 License

MIT © carlosp0veda

🔗 Related Packages

• @tramo-digital/core - Core design system components
• @tramo-digital/react-ui - React component library
• @tramo-digital/vue-ui - Vue component library
• @tramo-digital/types - TypeScript definitions

📖 Documentation: [Open Design System Design System Docs](https://github.com/Open Design System/tramo-digital-main)