@seyuna/postcss 1.0.0-canary.14 → 1.0.0-canary.16

package/.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Setup Node.js with npm auth
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           registry-url: https://registry.npmjs.org/
           scope: "@seyuna"
           always-auth: true

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [1.0.0-canary.16](https://github.com/seyuna-corp/seyuna-postcss/compare/v1.0.0-canary.15...v1.0.0-canary.16) (2026-01-10)
+
+
+### Bug Fixes
+
+* Fixed release configuration. ([3e7f764](https://github.com/seyuna-corp/seyuna-postcss/commit/3e7f76488e109110cbec50cb4c5bdc89397b3b40))
+* release configuration error. ([076eb34](https://github.com/seyuna-corp/seyuna-postcss/commit/076eb348d2ce7ca61bbc1c7a9ad597cadbe59f34))
+
+# [1.0.0-canary.15](https://github.com/seyuna-corp/seyuna-postcss/compare/v1.0.0-canary.14...v1.0.0-canary.15) (2026-01-09)
+
+
+### Bug Fixes
+
+* workflow node version upgrade. ([e98349a](https://github.com/seyuna-corp/seyuna-postcss/commit/e98349af69aab446f0ac4d0790112d5c702c1b36))
+
 # [1.0.0-canary.14](https://github.com/seyuna-corp/seyuna-postcss/compare/v1.0.0-canary.13...v1.0.0-canary.14) (2025-10-09)
 
 

package/README.md

@@ -0,0 +1,275 @@
+# @seyuna/postcss
+
+[![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.
+
+---
+
+## What is this
+
+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.
+
+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.
+
+```css
+html {
+  font-size: max(1rem, 0.833vw);
+}
+```
+
+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.
+
+---
+
+## Installation
+
+```bash
+npm install @seyuna/postcss postcss-import postcss-advanced-variables postcss-preset-env --save-dev
+```
+
+---
+
+## Configuration
+
+Create a `postcss.config.js` at your project root:
+
+```javascript
+import seyunaPostcss from '@seyuna/postcss';
+import postcssImport from 'postcss-import';
+import postcssAdvancedVariables from 'postcss-advanced-variables';
+import postcssPresetEnv from 'postcss-preset-env';
+
+export default {
+  plugins: [
+    seyunaPostcss({
+      configPath: 'seyuna.json',
+      modeAttribute: 'data-mode',
+    }),
+    postcssImport,
+    postcssAdvancedVariables,
+    postcssPresetEnv({
+      stage: 3,
+      features: {
+        'nesting-rules': true,
+      },
+    }),
+  ],
+};
+```
+
+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.
+
+---
+
+## The Color Model
+
+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.
+
+### 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.
+
+```css
+.button {
+  background: sc(primary);
+}
+```
+
+Compiles to:
+
+```css
+.button {
+  background: oklch(var(--lightness) var(--chroma) var(--primary-hue) / 1);
+}
+```
+
+### 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.
+
+```css
+.badge {
+  background: fc(white);
+}
+```
+
+Compiles to:
+
+```css
+.badge {
+  background: oklch(var(--white-lightness) var(--white-chroma) var(--white-hue) / 1);
+}
+```
+
+---
+
+## Color Manipulation
+
+All color functions accept a color name from your configuration.
+
+| 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.
+
+---
+
+## 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.
+
+```html
+<html data-mode="system">
+```
+
+The compiled CSS contains rules for all three states:
+
+```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:
+
+```css
+.card {
+  background: fc(white);
+
+  @dark {
+    background: fc(black);
+  }
+}
+```
+
+---
+
+## 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.
+
+```css
+.grid {
+  display: grid;
+  grid-template-columns: 1fr;
+
+  @md {
+    grid-template-columns: repeat(2, 1fr);
+  }
+
+  @lg {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+```
+
+Available breakpoints:
+
+| At-Rule | Container Width |
+|:--------|:----------------|
+| `@xs`   | 20rem           |
+| `@sm`   | 30rem           |
+| `@md`   | 48rem           |
+| `@lg`   | 62rem           |
+| `@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.
+
+---
+
+## Palette Iteration
+
+Generate utility classes by iterating over your entire color configuration:
+
+```css
+@each-standard-color {
+  .bg-{name} {
+    background-color: sc({name});
+  }
+}
+
+@each-fixed-color {
+  .text-{name} {
+    color: fc({name});
+  }
+}
+```
+
+---
+
+## The Reset Layer
+
+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.
+
+The upscaling magic happens here:
+
+```css
+html {
+  font-size: max(1rem, 0.833vw);
+}
+```
+
+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
+
+MIT

package/dist/at-rules/color-scheme.d.ts

@@ -0,0 +1,4 @@
+import { AtRule } from "postcss";
+import { PluginContext } from "../config";
+export declare const light: (atRule: AtRule, context: PluginContext) => void;
+export declare const dark: (atRule: AtRule, context: PluginContext) => void;

package/dist/at-rules/color-scheme.js

@@ -0,0 +1,43 @@
+import { Rule, AtRule } from "postcss";
+/**
+ * Custom PostCSS plugin handler factory for `@light` and `@dark` at-rules.
+ */
+function createColorSchemeHandler(scheme) {
+    return (atRule, context) => {
+        const { options } = context;
+        const modeAttribute = options.modeAttribute;
+        const clonedNodes = [];
+        // Clone all child nodes inside the block
+        atRule.each((node) => {
+            clonedNodes.push(node.clone());
+        });
+        /**
+         * Rule 1: [data-mode="scheme"] & { ... } (Explicit mode)
+         */
+        const explicitRule = new Rule({
+            selector: `[${modeAttribute}="${scheme}"] &`,
+            source: atRule.source,
+        });
+        clonedNodes.forEach((node) => explicitRule.append(node.clone()));
+        /**
+         * Rule 2: @media (prefers-color-scheme: scheme) { [data-mode="system"] & { ... } } (System preference)
+         */
+        const mediaAtRule = new AtRule({
+            name: "media",
+            params: `(prefers-color-scheme: ${scheme})`,
+            source: atRule.source,
+        });
+        const systemRule = new Rule({
+            selector: `[${modeAttribute}="system"] &`,
+            source: atRule.source,
+        });
+        clonedNodes.forEach((node) => systemRule.append(node.clone()));
+        mediaAtRule.append(systemRule);
+        /**
+         * Replace the original at-rule with the generated rules.
+         */
+        atRule.replaceWith(mediaAtRule, explicitRule);
+    };
+}
+export const light = createColorSchemeHandler('light');
+export const dark = createColorSchemeHandler('dark');

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

@@ -1,9 +1,10 @@
 import { AtRule } from "postcss";
+import { PluginContext } from "../config";
 /**
  * Handler for @each-standard-color
  */
-export declare function eachStandardColor(atRule: AtRule): void;
+export declare function eachStandardColor(atRule: AtRule, context: PluginContext): void;
 /**
  * Handler for @each-fixed-color
  */
-export declare function eachFixedColor(atRule: AtRule): void;
+export declare function eachFixedColor(atRule: AtRule, context: PluginContext): void;

package/dist/at-rules/color.js

@@ -1,21 +1,11 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.eachStandardColor = eachStandardColor;
-exports.eachFixedColor = eachFixedColor;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const helpers_1 = require("../helpers");
+import { generateRules } from "../helpers";
 /**
  * Handler for @each-standard-color
  */
-function eachStandardColor(atRule) {
-    const jsonPath = path_1.default.resolve(process.cwd(), "seyuna.json");
-    const data = JSON.parse(fs_1.default.readFileSync(jsonPath, "utf-8"));
-    const hueNames = Object.keys(data.ui.theme.hues);
-    const rules = (0, helpers_1.generateRules)(hueNames, atRule);
+export function eachStandardColor(atRule, context) {
+    const { config } = context;
+    const hueNames = config.ui ? Object.keys(config.ui.theme.hues) : [];
+    const rules = generateRules(hueNames, atRule, context);
     if (rules.length)
         atRule.replaceWith(...rules);
     else
@@ -24,16 +14,15 @@ function eachStandardColor(atRule) {
 /**
  * Handler for @each-fixed-color
  */
-function eachFixedColor(atRule) {
-    const jsonPath = path_1.default.resolve(process.cwd(), "seyuna.json");
-    const data = JSON.parse(fs_1.default.readFileSync(jsonPath, "utf-8"));
+export function eachFixedColor(atRule, context) {
+    const { config } = context;
     const mergedNames = [
         ...new Set([
-            ...Object.keys(data.ui.theme.light.colors),
-            ...Object.keys(data.ui.theme.dark.colors),
+            ...(config.ui ? Object.keys(config.ui.theme.light.colors) : []),
+            ...(config.ui ? Object.keys(config.ui.theme.dark.colors) : []),
         ]),
     ];
-    const rules = (0, helpers_1.generateRules)(mergedNames, atRule);
+    const rules = generateRules(mergedNames, atRule, context);
     if (rules.length)
         atRule.replaceWith(...rules);
     else

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

@@ -1,4 +1,5 @@
 import { AtRule } from "postcss";
+import { PluginContext } from "../config";
 /**
  * Custom PostCSS plugin handler for responsive at-rules.
  *
@@ -15,4 +16,4 @@ import { AtRule } from "postcss";
  *   }
  *
  */
-export default function container(atRule: AtRule): void;
+export default function container(atRule: AtRule, context: PluginContext): void;

package/dist/at-rules/container.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = container;
-const postcss_1 = require("postcss");
+import { AtRule } from "postcss";
 /**
  * Custom PostCSS plugin handler for responsive at-rules.
  *
@@ -18,9 +15,10 @@ const postcss_1 = require("postcss");
  *   }
  *
  */
-function container(atRule) {
-    // Map of shortcuts → container widths
-    const breakpoints = {
+export default function container(atRule, context) {
+    const { config } = context;
+    // Default breakpoints
+    const defaultBreakpoints = {
         xs: "20rem",
         sm: "40rem",
         md: "48rem",
@@ -28,15 +26,21 @@ function container(atRule) {
         xl: "80rem",
         "2xl": "96rem",
     };
+    // Merge with config if available (assuming config.ui.breakpoints exists)
+    const breakpoints = {
+        ...defaultBreakpoints,
+        ...(config.ui?.theme?.breakpoints || {}),
+    };
     if (Object.keys(breakpoints).includes(atRule.name)) {
         const minWidth = breakpoints[atRule.name];
         const clonedNodes = [];
         atRule.each((node) => {
             clonedNodes.push(node.clone());
         });
-        const containerAtRule = new postcss_1.AtRule({
+        const containerAtRule = new AtRule({
             name: "container",
             params: `(min-width: ${minWidth})`,
+            source: atRule.source,
         });
         clonedNodes.forEach((node) => containerAtRule.append(node));
         atRule.replaceWith(containerAtRule);

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

@@ -1,6 +1,7 @@
-import type { AtRule } from "postcss";
+import { AtRule } from "postcss";
+import { PluginContext } from "../config";
 export interface AtRuleHandler {
     name: string;
-    handler: (atRule: AtRule) => void;
+    handler: (atRule: AtRule, context: PluginContext) => void;
 }
 export declare const atRuleHandlers: AtRuleHandler[];

package/dist/at-rules/index.js

@@ -1,25 +1,16 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.atRuleHandlers = void 0;
-// atRuleHandlers.ts
-const dark_1 = __importDefault(require("./dark"));
-const light_1 = __importDefault(require("./light"));
-const container_1 = __importDefault(require("./container"));
-const color_1 = require("./color");
+import { eachStandardColor, eachFixedColor } from "./color";
+import container from "./container";
+import { light, dark } from "./color-scheme";
 // Ordered array ensures execution order
-exports.atRuleHandlers = [
-    { name: "each-standard-color", handler: color_1.eachStandardColor }, // first
-    { name: "each-fixed-color", handler: color_1.eachFixedColor },
-    { name: "light", handler: light_1.default },
-    { name: "dark", handler: dark_1.default },
-    { name: "xs", handler: container_1.default },
-    { name: "sm", handler: container_1.default },
-    { name: "md", handler: container_1.default },
-    { name: "lg", handler: container_1.default },
-    { name: "xl", handler: container_1.default },
-    { name: "2xl", handler: container_1.default },
-    // add more handlers here as needed
+export const atRuleHandlers = [
+    { name: "each-standard-color", handler: eachStandardColor },
+    { name: "each-fixed-color", handler: eachFixedColor },
+    { name: "light", handler: light },
+    { name: "dark", handler: dark },
+    { name: "xs", handler: container },
+    { name: "sm", handler: container },
+    { name: "md", handler: container },
+    { name: "lg", handler: container },
+    { name: "xl", handler: container },
+    { name: "2xl", handler: container },
 ];

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+import { SeyunaConfig } from './types';
+import { FunctionMap } from './parser';
+export interface PluginOptions {
+    configPath?: string;
+    modeAttribute?: string;
+    strict?: boolean;
+    config?: SeyunaConfig;
+    functions?: FunctionMap;
+}
+export interface PluginContext {
+    config: SeyunaConfig;
+    options: Required<PluginOptions>;
+    functions: FunctionMap;
+}
+export declare function loadConfig(options?: PluginOptions): {
+    config: SeyunaConfig;
+    options: Required<PluginOptions>;
+};

package/dist/config.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+const DEFAULT_OPTIONS = {
+    configPath: 'seyuna.json',
+    modeAttribute: 'data-mode',
+    strict: false,
+    config: undefined,
+    functions: undefined,
+};
+let cachedConfig = null;
+let cachedConfigPath = null;
+export function loadConfig(options = {}) {
+    const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
+    if (mergedOptions.config) {
+        return { config: mergedOptions.config, options: mergedOptions };
+    }
+    const configPath = path.resolve(process.cwd(), mergedOptions.configPath);
+    // Cache config if it's the same path
+    if (cachedConfig && cachedConfigPath === configPath) {
+        return { config: cachedConfig, options: mergedOptions };
+    }
+    try {
+        if (!fs.existsSync(configPath)) {
+            if (mergedOptions.strict) {
+                throw new Error(`Seyuna config not found at ${configPath}`);
+            }
+            return {
+                config: { ui: { theme: { hues: {}, light: { colors: {} }, dark: { colors: {} } } } },
+                options: mergedOptions,
+            };
+        }
+        const data = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        cachedConfig = data;
+        cachedConfigPath = configPath;
+        return { config: data, options: mergedOptions };
+    }
+    catch (error) {
+        if (mergedOptions.strict) {
+            throw error;
+        }
+        console.warn(`[Seyuna PostCSS] Warning: Failed to load config: ${error instanceof Error ? error.message : String(error)}`);
+        return {
+            config: { ui: { theme: { hues: {}, light: { colors: {} }, dark: { colors: {} } } } },
+            options: mergedOptions,
+        };
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+import { Node } from 'postcss';
+import { PluginContext } from './config';
+export declare function reportError(message: string, node: Node, context: PluginContext, options?: {
+    word?: string;
+    index?: number;
+}): void;
+export declare function reportWarning(message: string, node: Node): void;

package/dist/errors.js

@@ -0,0 +1,14 @@
+export function reportError(message, node, context, options = {}) {
+    const { options: pluginOptions } = context;
+    const formattedMessage = `[Seyuna PostCSS] ${message}`;
+    if (pluginOptions.strict) {
+        throw node.error(formattedMessage, options);
+    }
+    else {
+        reportWarning(formattedMessage, node);
+    }
+}
+export function reportWarning(message, node) {
+    const result = node.root().toResult();
+    node.warn(result, `[Seyuna PostCSS] ${message}`);
+}

package/dist/functions/color.d.ts

@@ -1,2 +1,7 @@
-export declare function sc(name: string, alpha?: string, lightness?: string, chroma?: string): string;
-export declare function fc(name: string, alpha?: string, lightness?: string, chroma?: string): string;
+import { PluginContext } from "../config";
+export declare function sc(context: PluginContext, name: string, alpha?: string, lightness?: string, chroma?: string): string;
+export declare function fc(context: PluginContext, name: string, alpha?: string, lightness?: string, chroma?: string): string;
+export declare function alpha(context: PluginContext, color: string, value: string): string;
+export declare function lighten(context: PluginContext, color: string, amount: string): string;
+export declare function darken(context: PluginContext, color: string, amount: string): string;
+export declare function contrast(context: PluginContext, color: string): string;