@seyuna/postcss 1.0.0-canary.37 → 1.0.0-canary.39

package/README.md

@@ -3,91 +3,65 @@
 [![NPM Version](https://img.shields.io/npm/v/@seyuna/postcss.svg)](https://www.npmjs.com/package/@seyuna/postcss)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> Design once. Deploy everywhere. Light and dark, effortlessly.
+> A CSS compiler for theme-aware design tokens.
 
 ---
 
-## Philosophy
+## Overview
 
-Seyuna PostCSS is not just another CSS preprocessor. It's a design system compiler that embraces four core principles:
+`@seyuna/postcss` is a PostCSS plugin that turns Seyuna-specific CSS syntax into plain CSS.
 
-### 1. Design Once at 1080p, Deploy Everywhere
+It is designed for projects that want:
 
-Traditional responsive design means designing the same component three or four times for different screen sizes. Seyuna takes a different approach: viewport-relative scaling.
+- design tokens declared directly in CSS
+- theme-aware colors without runtime JavaScript
+- reusable light/dark/system mode styling
+- container query shortcuts
+- generated utility-like selectors from token lists
 
-```css
-html {
-  font-size: max(1rem, 0.833vw);
-}
-```
-
-At 1920px viewport width, `0.833vw` equals exactly `16px`. On a 4K display, everything scales proportionally. Your 1080p design becomes a 4K design automatically. No breakpoints. No media queries. No redesigning.
-
-### 2. Seamless Dark / Light Mode
-
-Theme switching shouldn't require duplicating your entire stylesheet. With Seyuna, colors are defined once and adapt automatically:
-
-```css
-.button {
-  background: SeyunaStandardColor(primary);
-}
-```
+In practice, you write Seyuna syntax such as:
 
-When the user switches from light to dark mode, every standard color updates its lightness and chroma automatically. No conditional classes. No theme-specific stylesheets.
+- `@config "seyuna"` for tokens and theme settings
+- `@seyuna;` to inject the generated design system
+- helper functions like `SeyunaTone(primary)` and `SeyunaSwatch(brand)`
+- at-rules like `@dark`, `@light`, `@xs`, `@each-tone`, and `@each-swatch`
 
-### 3. Cleaner Codebase
+Seyuna compiles that into regular CSS:
 
-CSS shouldn't be bloated with repetitive color definitions and hardcoded values. Seyuna keeps your stylesheets lean:
+- custom properties
+- light and dark mode selectors
+- system preference media queries
+- container queries
+- repeated selectors for palette iteration
+- a global reset and layer setup
 
-```css
-/* Instead of this */
-.card {
-  background: rgba(66, 133, 244, 0.5);
-  border: 1px solid rgba(66, 133, 244, 0.8);
-}
+The important idea is that the source stays token-driven, but the browser receives standard CSS with no JavaScript color runtime.
 
-/* Write this */
-.card {
-  background: SeyunaAlpha(primary, 0.5);
-  border: 1px solid SeyunaAlpha(primary, 0.8);
-}
-```
-
-Your color palette is defined directly in your CSS. Your stylesheets reference colors by name. Change a value once in `@config`, and it updates everywhere.
+---
 
-### 4. Seamless Color Functions
+## Core Idea
 
-Need a hover state that's slightly lighter? A disabled state that's more transparent? Seyuna provides color manipulation functions that work with your design tokens:
+Seyuna works in three steps:
 
-```css
-.button {
-  background: SeyunaStandardColor(primary);
-}
-
-.button:hover {
-  background: SeyunaLighten(primary, 0.1);
-}
-
-.button:disabled {
-  background: SeyunaAlpha(primary, 0.3);
-}
-```
+1. Define tokens in CSS with `@config "seyuna"`.
+2. Generate the runtime variables and theme rules with `@seyuna;`.
+3. Reference those generated variables through helper functions like `SeyunaTone()` and `SeyunaAlpha()`.
 
-These functions compile to pure CSS using `calc()` and CSS custom properties. No JavaScript runtime. No color processing at page load.
+That means your source CSS stays token-based, while the browser receives plain CSS variables and selectors.
 
 ---
 
 ## Quick Start
 
-### Installation
+### Install
 
 ```bash
 npm install @seyuna/postcss postcss-import postcss-advanced-variables postcss-preset-env --save-dev
 ```
 
-### PostCSS Configuration
+### Configure PostCSS
 
-```javascript
+```js
 // postcss.config.js
 import seyunaPostcss from "@seyuna/postcss";
 import postcssImport from "postcss-import";
@@ -96,9 +70,9 @@ import postcssPresetEnv from "postcss-preset-env";
 
 export default {
   plugins: [
+    postcssImport(),
     seyunaPostcss(),
-    postcssImport,
-    postcssAdvancedVariables,
+    postcssAdvancedVariables(),
     postcssPresetEnv({
       stage: 3,
       features: {
@@ -109,138 +83,442 @@ export default {
 };
 ```
 
-### CSS Setup
+### Recommended Plugin Order
+
+Seyuna should run early in the pipeline.
 
-Configure your design tokens directly in your CSS using the `@config "seyuna"` at-rule, and then initialize the design system using `@seyuna;`:
+- `postcss-import()` first if your CSS is split across files
+- `seyunaPostcss()` next so it can see `@config`, `@seyuna`, and Seyuna helper functions before another plugin rewrites them
+- nesting and other syntax transforms after that
+
+If Seyuna runs too late, another plugin may already have removed or changed the syntax it needs to process.
+
+---
+
+## Smallest Working Example
 
 ```css
 @config "seyuna" {
-  /* Define hues (0-360) */
   --hue-primary: 240;
-  --hue-secondary: 30;
-
-  /* Define fixed colors (lightness chroma hue) */
-  --color-white: 1 0 0;
-  --color-black: 0 0 0;
-
-  /* Configure theme modes */
   --light-lightness: 0.66;
   --light-chroma: 0.26;
+  --dark-lightness: 0.78;
+  --dark-chroma: 0.18;
   --light-background: 1 0 0;
   --light-text: 0 0 0;
-
-  --dark-lightness: 0.66;
-  --dark-chroma: 0.26;
   --dark-background: 0 0 0;
   --dark-text: 1 0 0;
 }
 
 @seyuna;
 
-/* Your styles here */
+.button {
+  background: SeyunaTone(primary);
+  color: SeyunaContrast(primary);
+}
+
+.button:hover {
+  background: SeyunaTint(primary, 0.06);
+}
+```
+
+What this does:
+
+1. `--hue-primary` defines the hue token named `primary`.
+2. `--light-lightness` and `--dark-lightness` define the base lightness used by theme-aware standard colors.
+3. `--light-chroma` and `--dark-chroma` define the base chroma used by theme-aware standard colors.
+4. `@seyuna;` injects the variables, theme selectors, and reset.
+5. `SeyunaTone(primary)` resolves to an `oklch(...)` color using the current theme's `--lightness`, `--chroma`, and the `--primary-hue`.
+6. `SeyunaTint(primary, 0.06)` creates a lighter version of the same standard color.
+
+---
+
+## How `@config "seyuna"` Works
+
+`@config "seyuna"` is a build-time configuration block written directly in CSS.
+
+The plugin reads its custom properties, merges them into the Seyuna theme config, and removes the block from the final output.
+
+You can have one `@config "seyuna"` block or several. If there are several, they are merged in source order.
+
+Example:
+
+```css
+@config "seyuna" {
+  --hue-primary: 240;
+}
+
+@config "seyuna" {
+  --dark-lightness: 0.8;
+}
 ```
 
-The `@config` rule is parsed and removed at build time. It populates:
+That behaves as one combined configuration.
+
+---
+
+## What `@seyuna;` Injects
+
+`@seyuna;` expands the config into runtime CSS.
+
+It injects:
+
+- the global Seyuna reset and cascade layers
+- `:root` hue variables such as `--primary-hue`
+- `:root` fixed color variables such as `--brand-lightness`, `--brand-chroma`, and `--brand-hue`
+- `[data-mode="light"]` and `[data-mode="dark"]` blocks
+- system preference media queries for `[data-mode="system"]`
 
-- CSS custom properties for all your colors and hues
-- Theme mode selectors (`[data-mode="light"]`, `[data-mode="dark"]`)
-- System preference media queries
-- A modern CSS reset with cascade layers
+Use `@seyuna;` once in the compiled stylesheet output. If it appears multiple times, Seyuna keeps the first one and warns about the duplicates.
 
 ---
 
-## Color System
+## Understanding the Color Model
 
-Seyuna operates entirely in the **OKLCH color space**.
+Seyuna uses **OKLCH**.
+
+You do not usually write full `oklch(...)` values in your component styles. Instead, you define tokens and let the helpers produce the final colors.
+
+There are two kinds of color tokens:
 
 ### Standard Colors
 
-Standard colors define only a hue angle in the config and inherit theme lightness.
+Standard colors are hue-driven.
 
-### Default Hues
+They use:
 
-Seyuna comes with 24 default hues based on the Greek alphabet, spaced evenly at 15-degree increments:
+- a hue from `--hue-*`
+- a theme lightness from `--light-lightness` or `--dark-lightness`
+- a theme chroma from `--light-chroma` or `--dark-chroma`
 
-`alpha (15)`, `beta (30)`, `gamma (45)`, `delta (60)`, `epsilon (75)`, `zeta (90)`, `eta (105)`, `theta (120)`, `iota (135)`, `kappa (150)`, `lambda (165)`, `mu (180)`, `nu (195)`, `xi (210)`, `omicron (225)`, `pi (240)`, `rho (255)`, `sigma (270)`, `tau (285)`, `upsilon (300)`, `phi (315)`, `chi (330)`, `psi (345)`, `omega (360)`.
+That means standard colors automatically adapt between light and dark modes.
 
-You can use these directly without configuration, or override them in the `@config` block.
+Example:
 
 ```css
 @config "seyuna" {
-  --hue-alpha: 200; /* Override default Alpha hue */
+  --hue-primary: 240;
+  --light-lightness: 0.66;
+  --light-chroma: 0.26;
+  --dark-lightness: 0.78;
+  --dark-chroma: 0.18;
 }
 
-.badge {
-  background: SeyunaStandardColor(alpha);
+.button {
+  background: SeyunaTone(primary);
 }
 ```
 
+In light mode, `SeyunaTone(primary)` uses:
+
+- `var(--lightness)` from the light palette
+- `var(--chroma)` from the light palette
+- `var(--primary-hue)`
+
+In dark mode, the same function call uses the dark palette values instead.
+
 ### Fixed Colors
 
-Fixed colors have explicit lightness, chroma, and hue values. They can also be overridden per theme mode.
+Fixed colors are fully specified tokens.
+
+They use:
+
+- `--color-name: lightness chroma hue`
+
+and become three runtime variables:
+
+- `--name-lightness`
+- `--name-chroma`
+- `--name-hue`
+
+Example:
 
 ```css
 @config "seyuna" {
-  --color-white: 1 0 0;
-  --color-brand: 0.5 0.2 100; /* Global value */
-  --light-color-brand: 1 0 100; /* Light mode override */
+  --color-brand: 0.5 0.2 100;
 }
 
 .logo {
-  color: SeyunaFixedColor(white);
+  color: SeyunaSwatch(brand);
+}
+```
+
+Unlike standard colors, fixed colors do not depend on the theme-wide `--lightness` and `--chroma` values unless you override them per mode.
+
+---
+
+## What `--light-lightness` and `--dark-lightness` Actually Do
+
+This is the most important config concept to understand.
+
+`--light-lightness` and `--dark-lightness` do **not** define one specific named color.
+
+Instead, they define the base `--lightness` variable for the active theme mode:
+
+- `--light-lightness` becomes `--lightness` inside `[data-mode="light"]`
+- `--dark-lightness` becomes `--lightness` inside `[data-mode="dark"]`
+- both are also emitted inside the matching `prefers-color-scheme` media queries for `[data-mode="system"]`
+
+That `--lightness` value is then used by standard-color helpers such as:
+
+- `SeyunaTone()`
+- `SeyunaAlpha()` when the referenced token is a standard color
+- `SeyunaTint()` when the referenced token is a standard color
+- `SeyunaShade()` when the referenced token is a standard color
+- `SeyunaContrast()` when the referenced token is a standard color
+
+So this:
+
+```css
+@config "seyuna" {
+  --hue-primary: 240;
+  --light-lightness: 0.66;
+  --dark-lightness: 0.8;
 }
 
-.highlight {
-  background: SeyunaFixedColor(brand);
+.button {
+  background: SeyunaTone(primary);
 }
 ```
 
+means:
+
+- in light mode, `primary` uses lightness `0.66`
+- in dark mode, `primary` uses lightness `0.8`
+
+The same idea applies to `--light-chroma` and `--dark-chroma`. They define the shared `--chroma` variable for standard colors in each mode.
+
 ---
 
-## Color Functions
+## Theme Palette Properties
+
+Inside `@config "seyuna"`, theme-level properties control the generated palette for light and dark modes.
+
+### Shared Theme Controls
+
+These values shape standard colors in each mode:
+
+- `--light-lightness`
+- `--light-chroma`
+- `--dark-lightness`
+- `--dark-chroma`
+
+They are used to populate:
+
+- `--lightness`
+- `--chroma`
 
-| Function                       | Purpose                                   | Example                        |
-| :----------------------------- | :---------------------------------------- | :----------------------------- |
-| `SeyunaStandardColor(name)`    | Standard color with theme-aware lightness | `SeyunaStandardColor(primary)` |
-| `SeyunaFixedColor(name)`       | Fixed color with explicit values          | `SeyunaFixedColor(white)`      |
-| `SeyunaAlpha(color, value)`    | Adjusts opacity                           | `SeyunaAlpha(primary, 0.5)`    |
-| `SeyunaLighten(color, amount)` | Increases lightness                       | `SeyunaLighten(primary, 0.1)`  |
-| `SeyunaDarken(color, amount)`  | Decreases lightness                       | `SeyunaDarken(primary, 0.1)`   |
-| `SeyunaContrast(color)`        | Returns black or white for readability    | `SeyunaContrast(surface)`      |
+inside each generated mode selector.
 
-The `SeyunaContrast()` function uses dynamic CSS calculations. If the underlying color changes at runtime, the contrast color updates automatically.
+### Theme Surface Colors
+
+These values define the page-level background and text colors for each mode:
+
+- `--light-background`
+- `--light-text`
+- `--dark-background`
+- `--dark-text`
+
+Each one must be written as:
+
+```css
+lightness chroma hue
+```
+
+For example:
+
+```css
+--dark-background: 0 0 0;
+--dark-text: 1 0 0;
+```
+
+They become:
+
+- `--background`
+- `--text`
+
+inside the generated mode blocks.
+
+### Mode-Specific Fixed Color Overrides
+
+You can override a fixed color inside a specific mode by using:
+
+- `--light-color-*`
+- `--dark-color-*`
+
+Example:
+
+```css
+@config "seyuna" {
+  --color-brand: 0.5 0.2 100;
+  --light-color-brand: 0.92 0.05 100;
+}
+```
+
+That keeps `brand` global by default but changes it when light mode is active.
+
+---
+
+## Full Configuration Reference
+
+Within `@config "seyuna"`, the following prefixes are supported:
+
+| Prefix | What it means | Used by |
+| :----- | :------------ | :------ |
+| `--hue-*` | Defines a standard color hue token | `SeyunaTone`, standard-color `SeyunaAlpha`, `SeyunaTint`, `SeyunaShade`, `SeyunaContrast` |
+| `--color-*` | Defines a global fixed color as `lightness chroma hue` | `SeyunaSwatch`, fixed-color `SeyunaAlpha`, `SeyunaTint`, `SeyunaShade`, `SeyunaContrast` |
+| `--light-lightness` | Sets the base `--lightness` for light mode | Standard colors in light mode |
+| `--light-chroma` | Sets the base `--chroma` for light mode | Standard colors in light mode |
+| `--dark-lightness` | Sets the base `--lightness` for dark mode | Standard colors in dark mode |
+| `--dark-chroma` | Sets the base `--chroma` for dark mode | Standard colors in dark mode |
+| `--light-background` | Sets `--background` in light mode | Your global/page styling |
+| `--light-text` | Sets `--text` in light mode | Your global/page styling |
+| `--dark-background` | Sets `--background` in dark mode | Your global/page styling |
+| `--dark-text` | Sets `--text` in dark mode | Your global/page styling |
+| `--light-color-*` | Overrides a fixed color in light mode | Fixed colors in light mode |
+| `--dark-color-*` | Overrides a fixed color in dark mode | Fixed colors in dark mode |
+
+If a value is malformed, Seyuna warns and skips it rather than generating broken CSS.
+
+---
+
+## Color Helper Functions
+
+The `Seyuna` prefix is intentionally kept on the helper names so they are obviously custom and do not collide with CSS or other tooling.
+
+| Function | What it returns | Best use |
+| :------- | :-------------- | :------- |
+| `SeyunaTone(name)` | A theme-aware standard color | Buttons, accents, semantic hues |
+| `SeyunaSwatch(name)` | A fixed named color | Brand colors, literal palette tokens |
+| `SeyunaAlpha(color, value)` | The same color with a different alpha | Borders, overlays, subtle backgrounds |
+| `SeyunaTint(color, amount)` | A lighter version of the color | Hover states, active states |
+| `SeyunaShade(color, amount)` | A darker version of the color | Pressed states, stronger contrast |
+| `SeyunaContrast(color)` | A readable contrast color | Foreground text over token-driven backgrounds |
+
+### `SeyunaTone(name)`
+
+Uses:
+
+- `var(--lightness)`
+- `var(--chroma)`
+- `var(--name-hue)`
+
+Example:
+
+```css
+.button {
+  background: SeyunaTone(primary);
+}
+```
+
+### `SeyunaSwatch(name)`
+
+Uses:
+
+- `var(--name-lightness)`
+- `var(--name-chroma)`
+- `var(--name-hue)`
+
+Example:
+
+```css
+.logo {
+  color: SeyunaSwatch(brand);
+}
+```
+
+### `SeyunaAlpha(color, value)`
+
+Keeps the same base color but changes the alpha channel.
+
+Example:
+
+```css
+.overlay {
+  background: SeyunaAlpha(primary, 0.12);
+}
+```
+
+### `SeyunaTint(color, amount)`
+
+Adds to the lightness value using `calc(...)`.
+
+Example:
+
+```css
+.button:hover {
+  background: SeyunaTint(primary, 0.08);
+}
+```
+
+### `SeyunaShade(color, amount)`
+
+Subtracts from the lightness value using `calc(...)`.
+
+Example:
+
+```css
+.button:active {
+  background: SeyunaShade(primary, 0.08);
+}
+```
+
+### `SeyunaContrast(color)`
+
+Returns a black-or-white-style readable contrast color based on the color's lightness.
+
+Example:
+
+```css
+.badge {
+  background: SeyunaTone(primary);
+  color: SeyunaContrast(primary);
+}
+```
 
 ---
 
 ## Theme Switching
 
-Seyuna supports three modes: `light`, `dark`, and `system`. Control the active mode via the `data-mode` attribute:
+Seyuna supports three modes:
+
+- `light`
+- `dark`
+- `system`
+
+Use the `data-mode` attribute on a parent element, usually `<html>`:
 
 ```html
 <html data-mode="system"></html>
 ```
 
-### In-CSS Theme Overrides
+Behavior:
+
+- `[data-mode="light"]` forces the light palette
+- `[data-mode="dark"]` forces the dark palette
+- `[data-mode="system"]` follows `prefers-color-scheme`
 
-Need a component to look different in dark mode? Use the `@dark` and `@light` at-rules:
+### `@light` and `@dark`
+
+You can write mode-specific overrides directly in CSS:
 
 ```css
 .card {
-  background: SeyunaFixedColor(white);
+  background: SeyunaSwatch(white);
 
   @dark {
-    background: SeyunaFixedColor(black);
+    background: SeyunaSwatch(black);
   }
 }
 ```
 
-Compiles to rules that target both explicit mode selection and system preferences.
+This compiles to selectors for explicit mode choice and system preference behavior.
 
 ---
 
-## Container Queries
+## Container Query Shortcuts
 
-Seyuna includes shorthand breakpoints that compile to CSS Container Queries:
+Seyuna provides shorthand at-rules that compile to native `@container` rules:
 
 ```css
 .grid {
@@ -250,73 +528,83 @@ Seyuna includes shorthand breakpoints that compile to CSS Container Queries:
   @md {
     grid-template-columns: repeat(2, 1fr);
   }
-
-  @lg {
-    grid-template-columns: repeat(3, 1fr);
-  }
 }
 ```
 
-| At-Rule | Container Width |
-| :------ | :-------------- |
-| `@xs`   | 20rem           |
-| `@sm`   | 40rem           |
-| `@md`   | 48rem           |
-| `@lg`   | 64rem           |
-| `@xl`   | 80rem           |
-| `@2xl`  | 96rem           |
+Supported shorthands:
 
-Components respond to their container size, not the viewport. True component-based responsive design.
+| At-rule | Expands to |
+| :------ | :--------- |
+| `@xs` | `@container (min-width: 20rem)` |
+| `@sm` | `@container (min-width: 40rem)` |
+| `@md` | `@container (min-width: 48rem)` |
+| `@lg` | `@container (min-width: 64rem)` |
+| `@xl` | `@container (min-width: 80rem)` |
+| `@2xl` | `@container (min-width: 96rem)` |
+
+These react to the container, not the viewport, so components stay reusable in nested layouts.
 
 ---
 
 ## Palette Iteration
 
-Generate utility classes by iterating over your color configuration:
+Seyuna can generate repeated selectors from your token lists.
+
+The recommended shape is to pass a selector template as the at-rule parameter. This keeps the CSS parseable while still letting you generate class selectors.
+
+### `@each-tone "<selector-template>"`
+
+Iterates over the names in the standard hue map.
 
 ```css
-@each-standard-color {
-  .bg-{name} {
-    background-color: SeyunaStandardColor({name});
-  }
+@each-tone ".bg-{name}" {
+  background-color: SeyunaTone({name});
 }
+```
 
-@each-fixed-color {
-  .text-{name} {
-    color: SeyunaFixedColor({name});
-  }
+That generates selectors such as:
+
+- `.bg-primary`
+- `.bg-alpha`
+- `.bg-omega`
+
+### `@each-swatch "<selector-template>"`
+
+Iterates over fixed colors from:
+
+- global fixed colors declared with `--color-*`
+- light-mode fixed color overrides
+- dark-mode fixed color overrides
+
+```css
+@each-swatch ".text-{name}" {
+  color: SeyunaSwatch({name});
 }
 ```
 
----
-
-## Configuration Properties
+That generates selectors such as:
 
-Within the `@config "seyuna"` block, you can use the following property prefixes:
+- `.text-white`
+- `.text-black`
+- `.text-brand`
 
-| Prefix            | Description                                                      | Example                             |
-| :---------------- | :--------------------------------------------------------------- | :---------------------------------- |
-| `--hue-*`         | Defines a hue angle for a standard color                         | `--hue-primary: 240;`               |
-| `--color-*`       | Defines a global fixed color (L C H)                             | `--color-brand: 0.6 0.2 120;`       |
-| `--light-color-*` | Overrides a fixed color for light mode                           | `--light-color-brand: 0.8 0.1 120;` |
-| `--light-*`       | Configures the light theme (lightness, chroma, background, text) | `--light-lightness: 0.8;`           |
-| `--dark-color-*`  | Overrides a fixed color for dark mode                            | `--dark-color-brand: 0.4 0.1 120;`  |
-| `--dark-*`        | Configures the dark theme                                        | `--dark-background: 0 0 0;`         |
+`{name}` is replaced inside the selector template and inside declaration values.
 
-For colors and background/text, use a space-separated list of values: `lightness chroma hue`.
+If you write nested parseable selectors inside the block, Seyuna still replaces `{name}` there as well. But for class generation, the selector-template parameter is the easiest and safest approach.
 
 ---
 
-## Accessing Config Values
+## Common Gotchas
 
-Use `SeyunaTheme()` to access any value from your design tokens:
+- Run Seyuna early in the PostCSS chain.
+- Keep `@seyuna;` to a single final injection point.
+- Do not use the same token name for both a hue and a fixed color unless you intentionally want both variable shapes to exist.
+- If CSS is split across files, make sure the files containing `@config "seyuna"` and `@seyuna;` are processed together in the same build pipeline.
+- Prefer selector templates for palette iteration, e.g. `@each-tone ".bg-{name}"`.
 
-```css
-.container {
-  max-width: SeyunaTheme(ui.theme.breakpoints.lg);
-}
-```
+If output looks wrong, check plugin order first. That is the most common source of problems.
 
+---
 ---
 
 ## License