@seyuna/postcss 1.0.0-canary.27 → 1.0.0-canary.29

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.0.0-canary.29](https://github.com/seyuna-corp/seyuna-postcss/compare/v1.0.0-canary.28...v1.0.0-canary.29) (2026-01-21)
+
+
+### Features
+
+* allow mode-specific fixed color overrides in [@config](https://github.com/config) ([d41de2b](https://github.com/seyuna-corp/seyuna-postcss/commit/d41de2b4ef1f0d04ccd14584bcc150d21f9bbfcd))
+
+# [1.0.0-canary.28](https://github.com/seyuna-corp/seyuna-postcss/compare/v1.0.0-canary.27...v1.0.0-canary.28) (2026-01-21)
+
+
+### Features
+
+* move configuration from JSON to in-CSS [@config](https://github.com/config) at-rule ([964eabd](https://github.com/seyuna-corp/seyuna-postcss/commit/964eabdef0b1f63d600d0d1f2171387c2932f0b2))
+
 # [1.0.0-canary.27](https://github.com/seyuna-corp/seyuna-postcss/compare/v1.0.0-canary.26...v1.0.0-canary.27) (2026-01-20)
 
 

package/README.md

@@ -3,15 +3,17 @@
 [![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)
 
-> Build interfaces that transcend resolution.
+> Design once. Deploy everywhere. Light and dark, effortlessly.
 
 ---
 
-## What is this
+## Philosophy
 
-Seyuna PostCSS is the engine behind the Seyuna design system. It compiles a declarative color configuration into fully functional CSS, handles theme switching, and provides a suite of utilities that make authoring stylesheets faster and more intuitive.
+Seyuna PostCSS is not just another CSS preprocessor. It's a design system compiler that embraces four core principles:
 
-The core philosophy is simple: **design once at 1080p, deploy everywhere**. Seyuna UI handles upscaling automatically through viewport-relative font sizing. The result is pixel-perfect consistency from a laptop to a 4K display without breakpoints, without media queries, without you lifting a finger.
+### 1. Design Once at 1080p, Deploy Everywhere
+
+Traditional responsive design means designing the same component three or four times for different screen sizes. Seyuna takes a different approach: viewport-relative scaling.
 
 ```css
 html {
@@ -19,150 +21,203 @@ html {
 }
 ```
 
-This single line is the foundation. At 1920px viewport width, `0.833vw` equals exactly `16px`. Everything scales proportionally. No more designing three versions of every component.
+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
 
-## Installation
+Theme switching shouldn't require duplicating your entire stylesheet. With Seyuna, colors are defined once and adapt automatically:
 
-```bash
-npm install @seyuna/postcss postcss-import postcss-advanced-variables postcss-preset-env --save-dev
+```css
+.button {
+  background: SeyunaStandardColor(primary);
+}
+```
+
+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.
+
+### 3. Cleaner Codebase
+
+CSS shouldn't be bloated with repetitive color definitions and hardcoded values. Seyuna keeps your stylesheets lean:
+
+```css
+/* Instead of this */
+.card {
+  background: rgba(66, 133, 244, 0.5);
+  border: 1px solid rgba(66, 133, 244, 0.8);
+}
+
+/* Write this */
+.card {
+  background: SeyunaAlpha(primary, 0.5);
+  border: 1px solid SeyunaAlpha(primary, 0.8);
+}
+```
+
+Your color palette lives in `seyuna.json`. Your stylesheets reference it by name. Change the primary color once, and it updates everywhere.
+
+### 4. Seamless Color Functions
+
+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:
+
+```css
+.button {
+  background: SeyunaStandardColor(primary);
+}
+
+.button:hover {
+  background: SeyunaLighten(primary, 0.1);
+}
+
+.button:disabled {
+  background: SeyunaAlpha(primary, 0.3);
+}
 ```
 
+These functions compile to pure CSS using `calc()` and CSS custom properties. No JavaScript runtime. No color processing at page load.
+
 ---
 
-## Configuration
+## Quick Start
+
+### Installation
+
+```bash
+npm install @seyuna/postcss postcss --save-dev
+```
 
-Create a `postcss.config.js` at your project root:
+### PostCSS Configuration
 
 ```javascript
-import seyunaPostcss from '@seyuna/postcss';
-import postcssImport from 'postcss-import';
-import postcssAdvancedVariables from 'postcss-advanced-variables';
-import postcssPresetEnv from 'postcss-preset-env';
+// postcss.config.js
+import seyunaPostcss from "@seyuna/postcss";
 
 export default {
   plugins: [
     seyunaPostcss({
-      configPath: 'seyuna.json',
-      modeAttribute: 'data-mode',
-    }),
-    postcssImport,
-    postcssAdvancedVariables,
-    postcssPresetEnv({
-      stage: 3,
-      features: {
-        'nesting-rules': true,
-      },
+      modeAttribute: "data-mode",
     }),
   ],
 };
 ```
 
-The plugin reads from `seyuna.json` at build time. This file is your single source of truth for colors, themes, and any other design tokens you want accessible in CSS.
+### CSS Setup
+
+Configure your design tokens directly in your CSS using the `@config "seyuna"` at-rule, then import the design system:
+
+```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;
+  --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;
+}
+
+@import "seyuna";
+
+/* Your styles here */
+```
+
+The `@config` rule is parsed and removed at build time. It populates:
+
+- 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
 
 ---
 
-## The Color Model
+## Color System
 
-Seyuna operates entirely in the OKLCH color space. Unlike HSL or RGB, OKLCH is perceptually uniform. A lightness of `0.66` looks equally bright across all hues. This makes it possible to build harmonious palettes programmatically.
+Seyuna operates entirely in the **OKLCH color space**.
 
 ### Standard Colors
 
-Standard colors are hue-only tokens. They inherit the global `--lightness` and `--chroma` values from the current theme mode. When the user switches from light to dark, every standard color adapts automatically.
+Standard colors define only a hue angle in the config and inherit theme lightness.
 
 ```css
-.button {
-  background: sc(primary);
+@config "seyuna" {
+  --hue-primary: 240;
 }
-```
-
-Compiles to:
 
-```css
-.button {
-  background: oklch(var(--lightness) var(--chroma) var(--primary-hue) / 1);
+.badge {
+  background: SeyunaStandardColor(primary);
 }
 ```
 
 ### Fixed Colors
 
-Fixed colors are absolute. They define their own lightness, chroma, and hue. Use these for colors that must remain constant regardless of theme, like brand logos or semantic status indicators.
+Fixed colors have explicit lightness, chroma, and hue values.
 
 ```css
-.badge {
-  background: fc(white);
+@config "seyuna" {
+  --color-white: 1 0 0;
 }
-```
-
-Compiles to:
 
-```css
-.badge {
-  background: oklch(var(--white-lightness) var(--white-chroma) var(--white-hue) / 1);
+.logo {
+  color: SeyunaFixedColor(white);
 }
 ```
 
 ---
 
-## Color Manipulation
+## Color Functions
 
-All color functions accept a color name from your configuration.
+| 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)`      |
 
-| Function              | Purpose                                  | Example                     |
-|:----------------------|:-----------------------------------------|:----------------------------|
-| `alpha(color, value)` | Adjusts opacity                          | `alpha(primary, 0.5)`       |
-| `lighten(color, amt)` | Increases lightness by `amt`             | `lighten(primary, 0.1)`     |
-| `darken(color, amt)`  | Decreases lightness by `amt`             | `darken(primary, 0.1)`      |
-| `contrast(color)`     | Returns black or white based on lightness| `color: contrast(surface);` |
-
-The `contrast()` function uses a dynamic CSS calculation internally. It does not bake in a static value. If `--surface-lightness` changes at runtime, the contrast color updates with it.
+The `SeyunaContrast()` function uses dynamic CSS calculations. If the underlying color changes at runtime, the contrast color updates automatically.
 
 ---
 
 ## Theme Switching
 
-Seyuna supports three modes: `light`, `dark`, and `system`. The system mode respects `prefers-color-scheme`. All switching is handled via the `data-mode` attribute on your root element.
+Seyuna supports three modes: `light`, `dark`, and `system`. Control the active mode via the `data-mode` attribute:
 
 ```html
-<html data-mode="system">
+<html data-mode="system"></html>
 ```
 
-The compiled CSS contains rules for all three states:
+### In-CSS Theme Overrides
 
-```css
-[data-mode="light"] {
-  --lightness: 0.66;
-  --chroma: 0.26;
-}
-
-@media (prefers-color-scheme: dark) {
-  [data-mode="system"] {
-    --lightness: 0.66;
-    --chroma: 0.26;
-  }
-}
-```
-
-### In-CSS Overrides
-
-Need a component to look different in dark mode? Use the `@dark` and `@light` at-rules directly in your stylesheet:
+Need a component to look different in dark mode? Use the `@dark` and `@light` at-rules:
 
 ```css
 .card {
-  background: fc(white);
+  background: SeyunaFixedColor(white);
 
   @dark {
-    background: fc(black);
+    background: SeyunaFixedColor(black);
   }
 }
 ```
 
+Compiles to rules that target both explicit mode selection and system preferences.
+
 ---
 
 ## Container Queries
 
-Seyuna ships with shorthand breakpoints that compile to CSS Container Queries instead of traditional media queries. This means components respond to their container size, not the viewport.
+Seyuna includes shorthand breakpoints that compile to CSS Container Queries:
 
 ```css
 .grid {
@@ -179,95 +234,76 @@ Seyuna ships with shorthand breakpoints that compile to CSS Container Queries in
 }
 ```
 
-Available breakpoints:
-
 | At-Rule | Container Width |
-|:--------|:----------------|
+| :------ | :-------------- |
 | `@xs`   | 20rem           |
-| `@sm`   | 30rem           |
+| `@sm`   | 40rem           |
 | `@md`   | 48rem           |
-| `@lg`   | 62rem           |
+| `@lg`   | 64rem           |
 | `@xl`   | 80rem           |
 | `@2xl`  | 96rem           |
 
----
-
-## Configuration Reference
-
-```json
-{
-  "ui": {
-    "theme": {
-      "hues": {
-        "primary": 240,
-        "secondary": 30,
-        "accent": 150
-      },
-      "colors": {
-        "white": { "lightness": 1, "chroma": 0, "hue": 0 },
-        "black": { "lightness": 0, "chroma": 0, "hue": 0 }
-      },
-      "light": {
-        "lightness": 0.66,
-        "chroma": 0.26,
-        "background": { "lightness": 1, "chroma": 0, "hue": 0 },
-        "text": { "lightness": 0, "chroma": 0, "hue": 0 }
-      },
-      "dark": {
-        "lightness": 0.66,
-        "chroma": 0.26,
-        "background": { "lightness": 0, "chroma": 0, "hue": 0 },
-        "text": { "lightness": 1, "chroma": 0, "hue": 0 }
-      }
-    },
-    "mode": "system",
-    "output_dir": "src/styles"
-  }
-}
-```
-
-`hues` defines standard colors. Only the hue angle is specified because lightness and chroma come from the theme mode.
-
-`colors` defines fixed colors with explicit lightness, chroma, and hue values.
-
-`light` and `dark` set the global lightness and chroma for standard colors, plus any mode-specific fixed colors like background and text.
+Components respond to their container size, not the viewport. True component-based responsive design.
 
 ---
 
 ## Palette Iteration
 
-Generate utility classes by iterating over your entire color configuration:
+Generate utility classes by iterating over your color configuration:
 
 ```css
 @each-standard-color {
   .bg-{name} {
-    background-color: sc({name});
+    background-color: SeyunaStandardColor({name});
   }
 }
 
 @each-fixed-color {
   .text-{name} {
-    color: fc({name});
+    color: SeyunaFixedColor({name});
   }
 }
 ```
 
 ---
 
-## The Reset Layer
+## Configuration Properties
+
+Within the `@config "seyuna"` block, you can use the following property prefixes:
+
+| Prefix      | Description                                                      | Example                       |
+| :---------- | :--------------------------------------------------------------- | :---------------------------- |
+| `--hue-*`   | Defines a hue angle for a standard color                         | `--hue-primary: 240;`         |
+| `--color-*` | Defines a fixed color (L C H)                                    | `--color-brand: 0.6 0.2 120;` |
+| `--light-*` | Configures the light theme (lightness, chroma, background, text) | `--light-lightness: 0.8;`     |
+| `--dark-*`  | Configures the dark theme                                        | `--dark-background: 0 0 0;`   |
+
+For colors and background/text, use a space-separated list of values: `lightness chroma hue`.
+
+---
+
+## Plugin Options
 
-Seyuna UI generates a CSS file that includes a minimal, opinionated reset. It zeroes out margins and padding, removes default list styles, and sets sensible defaults for text rendering. The reset is applied to the `reset` layer, so your styles can override it without specificity battles.
+```javascript
+seyunaPostcss({
+  configPath: "seyuna.json", // Path to your config file
+  modeAttribute: "data-mode", // Attribute for theme switching
+  strict: false, // Throw errors for missing colors
+});
+```
 
-The upscaling magic happens here:
+---
+
+## Accessing Config Values
+
+Use `SeyunaTheme()` to access any value from your configuration:
 
 ```css
-html {
-  font-size: max(1rem, 0.833vw);
+.container {
+  max-width: SeyunaTheme(ui.theme.breakpoints.lg);
 }
 ```
 
-At 1920px, the computed font size is 16px. At 2560px, it becomes roughly 21px. Every `rem` value in your stylesheet scales accordingly. Design at 1080p. Ship at any resolution.
-
 ---
 
 ## License

package/dist/at-rules/config.d.ts

@@ -0,0 +1,6 @@
+import { PluginContext } from "../types.js";
+/**
+ * Handler for @config "seyuna"
+ * Parses the configuration defined directly in CSS.
+ */
+export declare function handleConfig(atRule: any, context: PluginContext): void;

package/dist/at-rules/config.js

@@ -0,0 +1,71 @@
+/**
+ * Handler for @config "seyuna"
+ * Parses the configuration defined directly in CSS.
+ */
+export function handleConfig(atRule, context) {
+    const params = atRule.params.replace(/['"]/g, "");
+    if (params === "seyuna") {
+        const { config } = context;
+        if (!config.ui) {
+            config.ui = {
+                theme: {
+                    hues: {},
+                    colors: {},
+                    light: {
+                        chroma: 0,
+                        lightness: 0,
+                        background: { lightness: 0, chroma: 0, hue: 0 },
+                        text: { lightness: 0, chroma: 0, hue: 0 },
+                        colors: {},
+                    },
+                    dark: {
+                        chroma: 0,
+                        lightness: 0,
+                        background: { lightness: 0, chroma: 0, hue: 0 },
+                        text: { lightness: 0, chroma: 0, hue: 0 },
+                        colors: {},
+                    },
+                },
+            };
+        }
+        const theme = config.ui.theme;
+        atRule.walkDecls((decl) => {
+            const prop = decl.prop;
+            const value = decl.value;
+            // Hues: --hue-alpha: 0;
+            if (prop.startsWith("--hue-")) {
+                const name = prop.replace("--hue-", "");
+                theme.hues[name] = parseFloat(value);
+            }
+            // Fixed Colors: --color-primary: 0.66 0.26 240;
+            else if (prop.startsWith("--color-")) {
+                const name = prop.replace("--color-", "");
+                const [l, c, h] = value.split(/\s+/).map(parseFloat);
+                theme.colors[name] = { lightness: l, chroma: c, hue: h };
+            }
+            // Theme Palettes: --light-lightness: 0.66;
+            else if (prop.startsWith("--light-") || prop.startsWith("--dark-")) {
+                const isLight = prop.startsWith("--light-");
+                const palette = isLight ? theme.light : theme.dark;
+                const key = prop.replace(isLight ? "--light-" : "--dark-", "");
+                if (key === "lightness")
+                    palette.lightness = parseFloat(value);
+                else if (key === "chroma")
+                    palette.chroma = parseFloat(value);
+                else if (key === "background" || key === "text") {
+                    const [l, c, h] = value.split(/\s+/).map(parseFloat);
+                    palette[key] = { lightness: l, chroma: c, hue: h };
+                }
+                else {
+                    // Custom colors in palette: --light-surface: 1 0 0;
+                    // Also supports overrides like --light-color-primary: 0.8 0.1 240;
+                    const cleanKey = key.replace(/^color-/, "");
+                    const [l, c, h] = value.split(/\s+/).map(parseFloat);
+                    palette.colors[cleanKey] = { lightness: l, chroma: c, hue: h };
+                }
+            }
+        });
+        // Remove the at-rule from CSS output
+        atRule.remove();
+    }
+}

package/dist/at-rules/import.js

@@ -7,9 +7,6 @@ import { fileURLToPath } from "url";
 import postcss from "postcss";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const STANDARD_HUES = [
-    'alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta', 'eta', 'theta', 'iota', 'kappa', 'lambda', 'mu', 'nu', 'xi', 'omicron', 'pi', 'rho', 'sigma', 'tau', 'upsilon', 'phi', 'chi', 'psi', 'omega'
-];
 /**
  * Handler for @import "seyuna"
  * Injects the core Seyuna Design System variables and base styles
@@ -48,14 +45,12 @@ export function handleImport(atRule, context) {
         }
         // 2. Global Hues and Base Colors (:root)
         const rootRule = new Rule({ selector: ":root", source: atRule.source });
-        // Process all hues from config plus defaults
-        const allHues = new Set([...STANDARD_HUES, ...Object.keys(theme.hues || {})]);
-        allHues.forEach((name) => {
-            const i = STANDARD_HUES.indexOf(name);
-            const defaultValue = i !== -1 ? i * 15 : 0;
-            const value = (theme.hues && theme.hues[name] !== undefined) ? theme.hues[name] : defaultValue;
-            rootRule.append(new Declaration({ prop: `--${name}-hue`, value: String(value) }));
-        });
+        // Process all hues from config
+        if (theme.hues) {
+            for (const [name, value] of Object.entries(theme.hues)) {
+                rootRule.append(new Declaration({ prop: `--${name}-hue`, value: String(value) }));
+            }
+        }
         // Add shared colors from theme.colors
         if (theme.colors) {
             for (const [name, color] of Object.entries(theme.colors)) {

package/dist/at-rules/index.js

@@ -3,8 +3,10 @@ import { eachStandardColor, eachFixedColor } from "./color.js";
 import container from "./container.js";
 import { light, dark } from "./color-scheme.js";
 import { handleImport } from "./import.js";
+import { handleConfig } from "./config.js";
 // Ordered array ensures execution order
 export const atRuleHandlers = [
+    { name: "config", handler: handleConfig },
     { name: "import", handler: handleImport },
     { name: "each-standard-color", handler: eachStandardColor },
     { name: "each-fixed-color", handler: eachFixedColor },

package/dist/config.d.ts

@@ -1,5 +1,5 @@
-import { SeyunaConfig, PluginOptions } from './types.js';
-export type { PluginOptions, PluginContext, FunctionMap } from './types.js';
+import { SeyunaConfig, PluginOptions } from "./types.js";
+export type { PluginOptions, PluginContext, FunctionMap } from "./types.js";
 export declare function loadConfig(options?: PluginOptions): {
     config: SeyunaConfig;
     options: Required<PluginOptions>;