@tenerife.music/ui 1.0.12 → 1.0.15

package/README.md

@@ -1,7 +1,7 @@
-# 🌴 Tenerife UI
+# 🌴 TUI
 
-**Premium React Component Library**  
-Elegant. Token-driven. Fully Typed. Built for Luxury Interfaces.
+**Token-driven UI architecture for long-living React products**
+Strict. Predictable. Built for system-level consistency.
 
 ![Release](https://img.shields.io/github/v/release/Tureckiy-zart/tenerife-ui?style=for-the-badge)
 ![React](https://img.shields.io/badge/React-18+-blue?style=for-the-badge)
@@ -10,504 +10,202 @@ Elegant. Token-driven. Fully Typed. Built for Luxury Interfaces.
 ![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Tureckiy-zart/tenerife-ui/main/.github/banner.png" width="100%" alt="Tenerife UI Banner" />
+  <img src="https://raw.githubusercontent.com/Tureckiy-zart/tenerife-ui/main/.github/banner.png" width="100%" alt="TUI Banner" />
 </p>
 
 <p align="center">
-  <strong>A high-quality, fully tokenized design system for modern React applications.<br/>
-  Built with Tailwind, CVA, TypeScript with a luxury-first aesthetic.</strong>
+  <strong>
+    A production-grade, token-driven design infrastructure for React applications.<br/>
+    Built on a locked Foundation layer, Radix UI behavioral primitives, and strict TypeScript contracts.
+  </strong>
 </p>
 
-> ⚠️ **Important:** The library is under active development. The API may change between versions. Use at your own risk. Thorough testing is recommended before using in production.
-
 ---
 
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-# npm
-npm install @tenerife.music/ui
-
-# pnpm
-pnpm add @tenerife.music/ui
+## 🧭 Architectural Manifest
 
-# yarn
-yarn add @tenerife.music/ui
-```
+TUI is **not a beginner-friendly UI library**.
 
-### Minimal Example
+This system is intentionally built for developers and teams who value
+**architectural consistency, long-term scalability, and system-level thinking**
+over quick experimentation or visual convenience.
 
-```tsx
-import { ThemeProvider, Button } from "@tenerife.music/ui";
+### This library is for you if:
 
-export default function App() {
-  return (
-    <ThemeProvider defaultMode="night">
-      <Button variant="default">Click me</Button>
-    </ThemeProvider>
-  );
-}
-```
+- 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 see constraints as a **feature**, not a limitation
+- You are comfortable trading short-term DX for long-term maintainability
 
-**Done!** 🎉 You can now use Tenerife UI components.
+### This library is NOT for you if:
 
-> 📖 **Need help?** See the [Complete Guide](./docs/GETTING_STARTED.md) for detailed installation and setup instructions.
+- 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
 
-## ✨ Key Features
+- **Tokens are the single source of truth**
+- **The Foundation layer is locked and immutable**
+- **Design decisions must be explicit and centralized**
+- **Constraints exist to protect the system — even from its author**
 
-- 🎨 **Token-driven architecture** — all styles through design tokens, no raw values
-- 🌓 **Day/Night modes** — automatic theme switching with system settings support
-- 🎯 **TypeScript-first** — full typing for all components and API
-- ♿ **Accessibility** — WCAG AA compliance out of the box, full keyboard and screen reader support
-- 📦 **Tree-shakeable** — bundle size optimization through named imports
-- 🎭 **CVA variants** — unified Variant API for all components
-- 🎨 **Tailwind CSS** — full integration with Tailwind preset
-- 🚀 **Production-ready** — tested and ready for production use
+If the system feels strict, uncomfortable, or limiting at first —
+that means it is working as intended.
 
 ---
 
-## 📚 Documentation
-
-| Document                                                  | Description                                            |
-| --------------------------------------------------------- | ------------------------------------------------------ |
-| **[Complete Guide](./docs/GETTING_STARTED.md)**           | Comprehensive guide for installation, setup, and usage |
-| [Quick Start](./docs/QUICK_START.md)                      | Get started in 30 seconds                              |
-| [API Reference](./docs/public-api.md)                     | Complete API documentation for all components          |
-| [Tokens Guide](./docs/TOKENS_GUIDE.md)                    | Working with design tokens                             |
-| [Theme Guide](./docs/THEME_GUIDE.md)                      | Theme setup and customization                          |
-| [Storybook](https://Tureckiy-zart.github.io/tenerife-ui/) | Interactive examples of all components                 |
+> ⚠️ **Status:** The Foundation layer is locked and stable. Extension components may evolve.
+> This system is actively developed for real production usage.
 
 ---
 
-## 🏗 Installation and Setup
-
-### Requirements
+## 🚀 Initial Setup
 
-- **React**: `^18 || ^19`
-- **React DOM**: `^18 || ^19`
-- **Node.js**: `>=22` (recommended)
-- **TypeScript**: `>=5.0` (optional, but recommended)
+Minimum setup required to evaluate and work with the system.
 
-### Step 1: Install Package
+### Installation
 
 ```bash
+# npm
 npm install @tenerife.music/ui
-npm install -D tailwindcss postcss autoprefixer
-```
-
-### Step 2: Configure Tailwind CSS
-
-Create `tailwind.config.ts`:
-
-```typescript
-import type { Config } from "tailwindcss";
-import preset from "@tenerife.music/ui/preset";
-
-const config: Config = {
-  content: [
-    "./src/**/*.{js,ts,jsx,tsx}",
-    "./node_modules/@tenerife.music/ui/dist/**/*.{js,ts,jsx,tsx}",
-  ],
-  presets: [preset],
-};
-
-export default config;
-```
-
-### Step 3: Import Styles
-
-In your application's root file:
-
-```typescript
-import "@tenerife.music/ui/styles";
-```
-
-### Step 4: Setup ThemeProvider
 
-```tsx
-import { ThemeProvider } from "@tenerife.music/ui";
+# pnpm
+pnpm add @tenerife.music/ui
 
-export default function App() {
-  return (
-    <ThemeProvider defaultMode="night" enableSystem={true}>
-      <YourApp />
-    </ThemeProvider>
-  );
-}
+# yarn
+yarn add @tenerife.music/ui
 ```
 
-> 📖 **Learn more:** See the [Complete Guide](./docs/GETTING_STARTED.md) for setup instructions for Next.js, Vite, Remix, and other frameworks.
-
----
-
-## 💡 Usage Examples
-
-### Basic Example
+### Minimal Example
 
 ```tsx
-import {
-  ThemeProvider,
-  Button,
-  Card,
-  CardHeader,
-  CardTitle,
-  CardContent,
-} from "@tenerife.music/ui";
+import { ThemeProvider, Button } from "@tenerife.music/ui";
 
 export default function App() {
   return (
     <ThemeProvider defaultMode="night">
-      <Card>
-        <CardHeader>
-          <CardTitle>Welcome</CardTitle>
-        </CardHeader>
-        <CardContent>
-          <Button variant="default">Get Started</Button>
-        </CardContent>
-      </Card>
-    </ThemeProvider>
-  );
-}
-```
-
-### Theme Toggle
-
-```tsx
-import { ThemeProvider, useTheme, Button } from "@tenerife.music/ui";
-
-function ThemeToggle() {
-  const { mode, toggleMode } = useTheme();
-
-  return (
-    <Button onClick={toggleMode} variant="outline">
-      {mode === "night" ? "☀️ Day" : "🌙 Night"}
-    </Button>
-  );
-}
-
-export default function App() {
-  return (
-    <ThemeProvider defaultMode="night" enableSystem={true}>
-      <ThemeToggle />
+      <Button variant="default">Click me</Button>
     </ThemeProvider>
   );
 }
 ```
 
-### Form with Validation
-
-```tsx
-import {
-  Field,
-  FieldLabel,
-  FieldControl,
-  FieldError,
-  Input,
-  Button,
-  Card,
-  CardHeader,
-  CardTitle,
-  CardContent,
-} from "@tenerife.music/ui";
-
-function ContactForm() {
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle>Contact Us</CardTitle>
-      </CardHeader>
-      <CardContent>
-        <form className="space-y-4">
-          <Field>
-            <FieldLabel>Email</FieldLabel>
-            <FieldControl asChild>
-              <Input type="email" placeholder="example@email.com" />
-            </FieldControl>
-            <FieldError>Email is required</FieldError>
-          </Field>
-          <Button type="submit" variant="default">
-            Submit
-          </Button>
-        </form>
-      </CardContent>
-    </Card>
-  );
-}
-```
-
-> 📖 **More examples:** See the [Complete Guide](./docs/GETTING_STARTED.md) for additional usage examples.
+> 📖 **Note:** This example demonstrates API shape only. Understanding the system
+> requires familiarity with tokens, variants, and architectural constraints.
 
 ---
 
-## 🧩 Components
-
-### Primitives
-
-Basic UI components for building interfaces:
-
-- **Button** — buttons with various variants (default, outline, destructive, ghost, link)
-- **Input** — text input fields with state support (success, error, warning)
-- **Textarea** — multi-line text input
-- **Label** — form field labels
-- **Card** — cards with variants (default, elevated, glass, outline)
-- **Badge** — badges for labels and statuses
-- **Text / Heading** — typography components
-
-### Forms
-
-Components for creating forms:
-
-- **Checkbox** — checkboxes with state support
-- **Radio / RadioGroup** — radio buttons and groups
-- **Select** — dropdown lists with search
-- **Field** — form field wrapper with validation
-- **FormInput / FormSelect / FormTextarea** — specialized form components
-
-### Layout
-
-Components for structuring layouts:
-
-- **Flex** — flexbox container with direction, alignment, and gap settings
-- **Grid** — responsive grid with breakpoint support
-- **Stack** — vertical/horizontal element placement
-- **Section** — sections with responsive padding
-- **Container** — containers with width constraints
-
-### Overlays
-
-Components for modal windows and popup elements:
-
-- **Modal** — modal windows with variants
-- **Dialog** — dialog windows (DialogRoot, DialogTrigger, DialogContent)
-- **Toast** — notifications with ToastProvider system
-- **Popover** — popup tooltips
-- **Tooltip** — tooltips for elements
-
-### Navigation
-
-Components for interface navigation:
-
-- **Tabs** — tabs with keyboard support
-- **Breadcrumbs** — breadcrumb navigation
-- **Pagination** — pagination with settings
-- **Stepper** — step-by-step forms
-- **SegmentedControl** — segmented control
-
-### Data
-
-Components for displaying data:
-
-- **Table** — tables with sorting and filtering
-- **DataList** — data lists (DataListRoot, DataListItem, DataListLabel, DataListValue)
-- **Skeleton** — loading state skeletons
-- **EmptyState** — empty states with actions
-
-### Notifications
+## ✨ Key Characteristics
 
-Notification system:
-
-- **NotificationCenter** — notification center with grouping
-- **Toast** — popup notifications
-
-### Domain Components
-
-Specialized components for specific domains:
-
-- **EventCard** — event cards with variants and sizes
-- **VenueCard** — venue cards
-- **ArtistCard** — artist cards
-- **TicketCard** — ticket cards
-- **PromoCard** — promo cards
-
-> 📖 **Full list:** See [API Reference](./docs/public-api.md) for a complete list of all components and their props.
+- 🎨 **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
 
 ---
 
-## 🎨 Design Tokens
-
-Tenerife UI uses a fully tokenized design system:
-
-### Colors
-
-- 100+ color tokens
-- Full color scales (primary, accent, secondary)
-- Surface tokens (base, elevated1-3, overlay, glass)
-- Semantic colors (success, error, warning, info)
-- Text colors (primary, secondary, tertiary, muted)
-- Day/night mode support
-
-### Typography
-
-- Fluid clamp scale for responsive sizes
-- 13 text styles
-- 9 font weights (thin - black)
-- 6 line-height variants
-- 6 letter-spacing variants
-
-### Spacing
-
-- 8px-based system (scale 0–96)
-- Semantic tokens (xs, sm, md, lg, xl, 2xl, 3xl, 4xl, 5xl)
-- Layout tokens (section padding, container widths, grid gaps)
-
-### Shadows
-
-- Elevation levels (none, xs, sm, md, lg, xl, 2xl)
-- Colored shadows (primary-_, accent-_)
-- Glow effects (primary-glow-subtle, primary-glow-medium)
-- Focus rings (focus-ring-default, focus-ring-primary)
-
-### Radius
-
-- Radius system (none, xs, sm, md, lg, xl, 2xl, 3xl, full)
-- Component standards (button, card, input, badge)
-
-### Motion
-
-- Durations (instant, fast, normal, slow, slower, slowest)
-- Easing functions (linear, ease-in, ease-out, ease-in-out, bounce, elastic)
-- Pre-configured transitions
-- Keyframes (fade, slide, scale, spin, pulse, bounce)
+## 📚 Documentation
 
-> 📖 **Learn more:** See the [Tokens Guide](./docs/TOKENS_GUIDE.md) for detailed information on working with tokens.
+| Document                  | Description                           |
+| ------------------------- | ------------------------------------- |
+| **Complete Guide**        | System overview and usage principles  |
+| Tokens Guide              | Design token structure and philosophy |
+| Theme Guide               | Theme configuration and modes         |
+| **Architecture Lock**     | Canonical architectural constraints   |
+| **Final Foundation Lock** | Authoritative source of truth         |
+| Storybook                 | Component examples and contracts      |
 
 ---
 
-## ⚙️ How Tenerife UI Works
+## 🏗 Architecture Overview
 
-### Token-first Architecture
+### Foundation Layer (Locked)
 
-No raw styles. Everything through tokens. This ensures consistency and easy customization.
+The Foundation layer defines **canonical behavior** and is **immutable**.
+There is exactly **one Foundation component per category**.
 
-### Tailwind + CSS Variables
+- Modal (Dialog)
+- Tabs
+- Select
+- ContextMenu
+- Toast
 
-Colors, spacing, shadows, radius — all generated automatically through Tailwind preset and CSS variables.
+All Foundation components:
 
-### CVA for Variability
+- delegate behavior to Radix UI
+- expose token-driven visual APIs
+- are backward-compatible and locked
 
-All components use Class Variance Authority (CVA) for a unified Variant API:
+### Extension Layer
 
-```tsx
-<Button variant="default" size="md">Click me</Button>
-<Button variant="outline" size="lg">Click me</Button>
-```
-
-### Strict TypeScript
+Extensions compose Foundation components or implement primitives
+that rely strictly on tokens and shared semantics.
 
-Full typing for all components, props, and API ensures excellent developer experience with autocomplete and type checking.
+Examples:
 
-### Theme Engine
-
-Instant switching between day/night modes with support for user system settings.
+- Button
+- Input / Textarea
+- Card / Badge
+- Layout primitives (Stack, Grid, Container)
+- Data and feedback components
 
 ---
 
-## 🔧 Development
-
-### Install Dependencies
-
-```bash
-pnpm install
-```
-
-### Run in Development Mode
-
-```bash
-pnpm dev
-```
-
-### Run Storybook
-
-```bash
-pnpm storybook
-```
-
-Storybook is available at `http://localhost:6006`
-
-### Testing
-
-```bash
-# Run tests
-pnpm test
-
-# Run tests with coverage
-pnpm test:coverage
+## 🎨 Design Tokens
 
-# Run accessibility tests
-pnpm test:a11y
-```
+TUI uses a fully tokenized design system:
 
-### Build
+- **Colors** — semantic, theme-aware
+- **Typography** — fluid, scalable
+- **Spacing** — semantic and layout-based
+- **Radius & Shadows** — consistent elevation model
+- **Motion** — durations and easing as tokens
 
-```bash
-pnpm build
-```
+Tokens are **immutable contracts**, not convenience variables.
 
-### Linting and Formatting
+---
 
-```bash
-# Check linting
-pnpm lint:check
+## 🧩 Domain-Specific Components
 
-# Fix linting errors
-pnpm lint:fix
+The following components are **used internally** in Tenerife Music projects
+and are **not generic UI primitives**:
 
-# Check formatting
-pnpm format:check
+- EventCard
+- VenueCard
+- ArtistCard
+- TicketCard
+- PromoCard
 
-# Format code
-pnpm format
-```
+> These components are tightly coupled to specific product domains
+> and are documented for reference, not as reusable primitives.
 
 ---
 
 ## 🛠 Contributing
 
-We welcome contributions to the library! Before starting, please read:
+Contributions are welcome **within the boundaries of the system**.
 
-- [TYPING_STANDARD.md](./docs/structure/TYPING_STANDARD.md) — typing standards
-- [STRUCTURE_OF_WORK.md](./docs/structure/STRUCTURE_OF_WORK.md) — work structure
-- [COMPONENT_GUIDELINES.md](./docs/structure/COMPONENT_GUIDELINES.md) — component guidelines
+> ⚠️ TUI follows a strict, opinionated architecture.
+> All contributions are expected to respect locked layers,
+> token ownership rules, and canonical constraints.
 
-### Contribution Process
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+Architectural discussions take precedence over visual changes.
 
 ---
 
 ## 📜 License
 
-MIT License — Commercial-friendly.
-
-Use in commercial projects is permitted without restrictions.
-
----
-
-## 🔗 Links
-
-- **Repository**: [https://github.com/Tureckiy-zart/tenerife-ui](https://github.com/Tureckiy-zart/tenerife-ui)
-- **Issues**: [https://github.com/Tureckiy-zart/tenerife-ui/issues](https://github.com/Tureckiy-zart/tenerife-ui/issues)
-- **Storybook**: [https://Tureckiy-zart.github.io/tenerife-ui/](https://Tureckiy-zart.github.io/tenerife-ui/)
-- **npm**: [https://www.npmjs.com/package/@tenerife.music/ui](https://www.npmjs.com/package/@tenerife.music/ui)
-
----
-
-## 🎤 From the Author
-
-Tenerife UI is my personal approach to creating a commercial, beautiful, and premium UI system.
-
-If you're building interfaces with a "luxury, stylish, and technological" aesthetic — you're home. 🏠
+MIT License — commercial use permitted.
 
 ---
 
 <p align="center">
-  <strong>Made with ❤️ for luxury projects</strong>
+  <strong>Built for long-term systems, not short-term convenience.</strong>
 </p>

package/dist/{colors-DPNI96bB.d.cts → colors-BZtZJBBm.d.cts}

@@ -286,4 +286,4 @@ declare const tailwindThemeColors: {
     };
 };
 
-export { type BaseColorTokens as B, type ColorScale as C, type Mode as M, type SurfaceColors as S, type TextColors as T, type ColorTokens as a, type SemanticColors as b, type ChartColors as c, cssVariableColorTokens as d, accentColors as e, surfaceColors as f, semanticColors as g, chartColors as h, textColors as i, baseColors as j, colorCSSVariables as k, primaryColors as p, secondaryColors as s, tailwindThemeColors as t };
+export { type BaseColorTokens as B, type ChartColors as C, type Mode as M, type SemanticColors as S, type TextColors as T, type ColorScale as a, type ColorTokens as b, type SurfaceColors as c, accentColors as d, baseColors as e, chartColors as f, colorCSSVariables as g, cssVariableColorTokens as h, semanticColors as i, surfaceColors as j, textColors as k, primaryColors as p, secondaryColors as s, tailwindThemeColors as t };

package/dist/{colors-DPNI96bB.d.ts → colors-BZtZJBBm.d.ts}

@@ -286,4 +286,4 @@ declare const tailwindThemeColors: {
     };
 };
 
-export { type BaseColorTokens as B, type ColorScale as C, type Mode as M, type SurfaceColors as S, type TextColors as T, type ColorTokens as a, type SemanticColors as b, type ChartColors as c, cssVariableColorTokens as d, accentColors as e, surfaceColors as f, semanticColors as g, chartColors as h, textColors as i, baseColors as j, colorCSSVariables as k, primaryColors as p, secondaryColors as s, tailwindThemeColors as t };
+export { type BaseColorTokens as B, type ChartColors as C, type Mode as M, type SemanticColors as S, type TextColors as T, type ColorScale as a, type ColorTokens as b, type SurfaceColors as c, accentColors as d, baseColors as e, chartColors as f, colorCSSVariables as g, cssVariableColorTokens as h, semanticColors as i, surfaceColors as j, textColors as k, primaryColors as p, secondaryColors as s, tailwindThemeColors as t };