🌴 TUI

Token-driven UI architecture for long-living React products Predictable. Built for system-level consistency.

Current Release: v3.1.0 (npm)
Next Release: [Unreleased] — See CHANGELOG

⚠️ Work in Progress / Experimental

@tenerife.music/ui is under active development and provided as is, without any guarantees of stability.

• Public API may change without prior notice
• Breaking changes may occur even in minor or patch releases
• Component behavior, tokens, and internal contracts may change in non-obvious ways
• Documentation may temporarily lag behind implementation

Use at your own risk, especially in production environments.

Versioning note

Semantic versioning reflects release coordination, not API stability. Minor and patch releases may include breaking changes.

🧭 Architectural Manifest

TUI is not a beginner-friendly UI library.

Built for teams who value architectural consistency and long-term scalability over quick experimentation or visual convenience.

This library is for you if:

• You build long-living products, not throwaway interfaces
• You want to prevent design entropy, not fight it later
• You prefer strict rules over flexible chaos
• You are comfortable trading short-term DX for long-term maintainability

This library is NOT for you if:

• You want to freely tweak styles with strings, numbers, or ad-hoc classes
• You expect “easy overrides” or escape hatches
• You are looking for a quick UI kit or experimentation playground
• You prefer visual freedom over architectural discipline

Core philosophy

• Tokens are the single source of truth
• The Foundation layer is locked and immutable

If the system feels strict or limiting — that means it is working as intended.

Public API contract

Only exports from the root entry @tenerife.music/ui are considered public. Deep imports are forbidden and may break without notice.

⚠️ Status: The Foundation layer is locked and stable. Extension components may evolve. A11Y (including contrast) is architecturally finalized and locked. See: docs/architecture/locks/A11Y_LOCK.md This system is actively developed for real production usage.

🚀 Initial Setup

Minimum setup required to evaluate and work with the system.

Installation

# npm
npm install @tenerife.music/ui

# pnpm
pnpm add @tenerife.music/ui

# yarn
yarn add @tenerife.music/ui

Minimal Example

import { ThemeProvider } from "@tenerife.music/ui/theme";
import { Button } from "@tenerife.music/ui";

export default function App() {
  return (
    <ThemeProvider defaultMode="night">
      <Button variant="primary">Click me</Button>
    </ThemeProvider>
  );
}

📖 Note: This example demonstrates API shape only. Understanding the system requires familiarity with tokens, variants, and architectural constraints.

Fonts (Optional)

TUI ships with system font fallbacks by default. We do not bundle or require fonts. If you want canonical visuals, you can load Inter / Clash Display / Satoshi in your app, but this is optional.

✨ Key Characteristics

• 🎨 Token-driven architecture — no raw values, no ad-hoc styles
• 🏛️ Radix UI behavioral foundation — accessibility and interactions are delegated
• 🔒 Locked Foundation layer — one canonical component per category
• 🧩 Extension-based composition — no Foundation duplication
• 🌓 Theme-aware tokens — day/night modes via semantic tokens
• 🎯 TypeScript-first API — strict, expressive, autocomplete-driven
• ♿ Accessibility-first — WCAG-compliant by design
• 🚫 No escape hatches — consistency over convenience

📚 Documentation

Public Docs

| Document | Description | Link | | ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------- | | Getting Started | Integration and setup guide | docs/reference/INTEGRATION_GUIDE.md | | API Reference | Public API documentation | docs/reference/API_REFERENCE.md | | Tokens Overview | Design token structure and philosophy | docs/reference/TOKENS_OVERVIEW.md | | Components Inventory | Complete component list | docs/reference/COMPONENTS_INVENTORY.md | | Documentation Hub | Complete documentation index | docs/README.md |

Storybook is used as an internal visual contract and can be run locally.

Advanced Architecture

• Architecture Context: docs/ARCHITECTURE_CONTEXT.md
• Foundation Lock: docs/architecture/FOUNDATION_LOCK.md
• Architecture Lock: docs/architecture/ARCHITECTURE_LOCK.md
• A11Y Lock: docs/architecture/locks/A11Y_LOCK.md
• Consumer Layout Guide: docs/architecture/closed-system/CONSUMER_LAYOUT_GUIDE.md

🏗 Architecture (High-level)

TUI is built on a strict multi-layer architecture:

• Foundation — locked tokens & primitives
• Primitives — atomic UI building blocks
• Composition — layout & interaction orchestration
• Patterns — reusable UI patterns
• Domain — product-specific components

→ Full architecture: docs/ARCHITECTURE_CONTEXT.md

🎨 Design Tokens

TUI uses a fully tokenized design system:

• Colors — semantic, theme-aware
• Typography — fluid, scalable
• Spacing — semantic and layout-based
• Radius & Shadows — consistent elevation model
• Motion — durations and easing as tokens

Tokens are immutable contracts, not convenience variables.

🎨 Theming

TUI consumes pre-generated themes. Theme authoring and validation tooling is documented separately: tools/theme-contract/README.md.

🧩 Product-Specific Extensions

The following components exist as product-level extensions and are not intended as generic UI primitives:

• EventCard
• VenueCard
• ArtistCard
• TicketCard
• PromoCard

These components are tightly coupled to specific product domains, are not part of the public API, and are documented for reference only. Use Card, Grid, and other public components to build custom layouts.

🛠 Contributing

Contributions are welcome within the boundaries of the system.

⚠️ TUI follows a strict, opinionated architecture. All contributions are expected to respect locked layers, token ownership rules, and canonical constraints.

Architectural discussions take precedence over visual changes.

Release Discipline

This project follows strict version canon synchronization rules:

• npm registry (@tenerife.music/ui) is the single source of truth for published versions
• Only versions published to npm may appear in CHANGELOG with publication dates
• Unreleased versions must be labeled as [Unreleased], not as current version
• All releases must go through the automated release process (no manual edits)

Verify versions:

npm view @tenerife.music/ui version
npm view @tenerife.music/ui versions --json

See CHANGELOG Version Canon Rules and Release Process for details.

Contributing & internal workflows → see CONTRIBUTING.md.

📜 License

MIT License — commercial use permitted.