StyleScript CSS

StyleScript CSS is a compile-first styling language for modern frontend teams. You write .ss files in a clean component-oriented syntax, and the compiler emits production-ready CSS.

It is designed to be:

• easy to read
• fast to write
• safe to scale
• compatible with existing CSS workflows

Table of Contents

1. Introduction
2. Core Features
3. Installation
4. Quick Start
5. Language Guide
6. Typed Variables
7. Components, Reuse, and Nesting
8. States and Pseudo Selectors
9. Responsive System
10. Theme Engine
11. Imports and Entry Files
12. CSS Power Features (At-Rules)
13. Batch 2 Productivity Features
14. Enforce Rules (Design System Guardrails)
15. Audit Command (Dead Style Detection)
16. CLI Reference
17. Config Reference
18. Node API Reference
19. Error Messages and Debugging
20. Best Practices
21. Development

1) Introduction

StyleScript compiles source styles through a deterministic pipeline:

source (.ss) -> parser -> AST -> generator -> transformer -> CSS output

You can use it for:

• design systems
• app UI component styling
• themeable products
• responsive layouts

2) Core Features

• Compile-first .ss DSL
• Typed variables with compile-time validation
• Component-scoped generation (.hash + [ui="Name"] selectors)
• State blocks (on hover, on focus-visible, etc.)
• Responsive shorthand (@sm, @md+, @sm..lg, etc.)
• Theme blocks (theme light, theme dark) with token resolution
• Nested selectors and parent selector (&)
• nestedComponent for nested UI parts
• Import graph support (@use, @forward)
• Design-system enforce rules
• Dead-style usage audit command
• Optional configurable property aliases
• Native CSS feature blocks (motion, font, capable, adapt)

3) Installation

npm install stylescript-css

Optional global CLI:

npm install -g stylescript-css

4) Quick Start

Initialize:

stylescript init --framework=vite

Build all styles:

stylescript build-all --minify

Watch mode:

stylescript dev

Single entry build:

stylescript build ./src/styles/main.ss ./dist/css/style.css --minify

5) Language Guide

Basic Example

let<color> brand = #2563eb

style buttonBase(pad) {
  background = $brand
  padding = $pad
  border-radius = 10
}

component Button {
  include buttonBase(12)
  color = #ffffff
}

Supported Friendly Keywords

• let / var: variables
• style / mixin: reusable style blocks
• func / fn: reusable callable blocks
• include / use: apply reusable block
• component: explicit component declaration
• on / state: state selector block
• when / if: condition block
• repeat ... from ... to ... / for ... in ...: loops

6) Typed Variables

Typed variables are validated at compile time.

let<px> spacing = 12
let<rem> textSize = 1.125
let<em> lineHeight = 1.4
let<color> brand = #0ea5e9
let<int> columns = 3
let<float> ratio = 1.25
let<percent> opacity = 80
let<string> family = "Manrope"

Alternative syntax:

let:color brand = #0ea5e9

Supported types:

• px, rem, em, color, int, float, percent, string

If invalid, compiler throws descriptive typed errors with source location.

7) Components, Reuse, and Nesting

Reusable Block + Include

style cardShell(pad) {
  padding = $pad
  border = 1 solid #dbe2ea
  border-radius = 14
}

component Card {
  include cardShell(16)
}

Nested Selectors

component Card {
  .title {
    font-size = 20
  }

  &:hover {
    border-color = #2563eb
  }
}

Nested Component Parts

Use nestedComponent instead of manually writing [ui="..."].

component Card {
  nestedComponent Title {
    font-size = 20
    font-weight = 700
  }

  nestedComponent Meta {
    color = #64748b
  }
}

8) States and Pseudo Selectors

State blocks support pseudo classes, pseudo elements, and advanced selectors.

component Button {
  on hover, focus-visible {
    color = #0f172a
  }

  on :has(.icon) {
    padding = 16
  }

  on ::before {
    content = ""
  }
}

You can also use parent selector patterns in state expressions:

component Button {
  on &:not(.is-loading) {
    opacity = 1
  }
}

9) Responsive System

Responsive Value Shorthand

component Card {
  padding = 8@sm 12@md 16@lg
  margin = 10@sm,md
  gap = 14@md+
  border-radius = [email protected]
  font-size = 14@-md
}

Patterns:

• @sm,md: apply value at multiple breakpoints
• @md+: apply from md and up
• @-md: apply up to and including md
• @sm..lg: apply over breakpoint range

Default breakpoints:

• xs: max-width: 480px
• sm: max-width: 640px
• md: (min-width: 641px) and (max-width: 1024px)
• lg: min-width: 1025px
• xl: min-width: 1280px
• 2xl: min-width: 1536px

Override with config breakpoints.

10) Theme Engine

theme light {
  bg = #ffffff
  text = #0f172a
  panel = #f8fafc
}

theme dark {
  bg = #0b1220
  text = #f8fafc
  panel = #162032
}

component Page {
  background = $theme.bg
  color = $theme.text
}

Token references:

• $theme.token
• $t.token

Behavior:

• Generates [data-theme="light"] and [data-theme="dark"] scoped output
• Auto-emits @media (prefers-color-scheme: dark) block for dark-theme styles

Build only one theme:

stylescript build-all --theme=dark
stylescript build-all --theme=light
stylescript build-all --theme=all

11) Imports and Entry Files

Use one main entry .ss and import other modules:

@use "./tokens";
@use "./mixins";
@forward "./components/card";

component Page {
  color = $textColor
}

Supported:

• relative paths
• extensionless imports
• partial files (_tokens.ss, _index.ss)
• nested import graphs
• cycle detection

Compile with entry path:

stylescript build ./src/styles/main.ss ./dist/css/style.css

12) CSS Power Features (At-Rules)

StyleScript supports both canonical and friendly forms.

Motion / Keyframes

motion fadeIn {
  start { opacity = 0 }
  step 50 { opacity = 0.5 }
  end { opacity = 1 }
}

component Hero {
  animation = fadeIn 300ms ease
}

Compiles to @keyframes.

Font Face

font {
  font-family = "Manrope"
  src = url("/fonts/manrope.woff2") format("woff2")
  font-weight = 400
}

Compiles to @font-face.

Supports

capable (display: grid) {
  .grid {
    display = grid
    gap = 12
  }
}

Compiles to @supports.

Container Query

adapt card-layout (min-width: 700px) {
  .item {
    padding = 20
  }
}

Compiles to @container.

13) Batch 2 Productivity Features

A) Intent-Based Layout

component Hero {
  layout = hero(40/60)
}

component Products {
  layout = cards(auto-fit, 240)
}

component Sidebar {
  layout = stack(16)
}

What it generates:

• hero(40/60) -> centered grid split (40% / 60%)
• cards(auto-fit, 240) -> responsive card grid with min width 240px
• stack(16) -> vertical flex stack with gap

B) Fluid Typography

component Title {
  font-size = fluid(32, 56, 360, 1440)
}

Compiles to clamp(...) for fluid scaling between viewport bounds.

C) Directional Logical Helpers (RTL/LTR Safe)

component Card {
  margin-start = 16
  margin-end = 16
  padding-start = 20
  padding-end = 20
  start = 12
  end = 12
}

Maps to logical properties:

• margin-inline-start, margin-inline-end
• padding-inline-start, padding-inline-end
• inset-inline-start, inset-inline-end

14) Enforce Rules (Design System Guardrails)

stylescript.config.json:

{
  "enforce": {
    "spacing": [4, 8, 12, 16, 24, 32, 48, 64],
    "colors": "only-vars",
    "font-size": [12, 14, 16, 18, 24, 32],
    "border-radius": [4, 8, 16, 9999]
  }
}

Shorthand config keys also accepted:

• space -> spacing
• fs -> font-size
• radius -> border-radius
• colorPolicy -> colors

Warn mode:

stylescript build-all --enforce=warn

15) Audit Command (Dead Style Detection)

Find unused UI styles:

stylescript audit --src=./src --framework=react
stylescript a --src=./src --framework=react

Auto-comment unused blocks:

stylescript audit --src=./src --framework=react --fix

Detected usage markers:

• ui="Component"
• data-ui="Component"
• uiName="Component"

16) CLI Reference

stylescript build <input.ss> <output.css> [--minify] [--compat=<full|basic|off>] [--targets="..."] [--sourcemap] [--theme=<dark|light|all>] [--enforce=warn]
stylescript build-all [inputDir] [outputTarget] [--minify] [--compat=<full|basic|off>] [--targets="..."] [--sourcemap] [--theme=<dark|light|all>] [--enforce=warn]
stylescript dev [inputDir] [outputTarget]
stylescript init [--framework=<vite|next|vanilla>]
stylescript migrate <input.(scss|sass|less|css)> [output.ss]
stylescript bench
stylescript audit --src=./src --framework=react [--fix]
stylescript a --src=./src --framework=react [--fix]

17) Config Reference

Supported config locations:

• stylescript.config.json
• stylescript.config.cjs
• stylescript.config.js
• package.json -> stylescript

Example:

{
  "inputDir": "src/styles",
  "outputTarget": "dist/css/style.css",
  "minify": true,
  "sourceMap": false,
  "compatMode": "full",
  "browserslist": ["last 2 versions", "not dead"],
  "breakpoints": {
    "sm": "max-width: 640px",
    "md": "(min-width: 641px) and (max-width: 1024px)",
    "lg": "min-width: 1025px"
  },
  "propertyAliases": {
    "p": "padding",
    "bg": "background"
  },
  "enforce": {
    "spacing": [4, 8, 12, 16],
    "colors": "only-vars"
  }
}

Property Aliases (Optional)

By default, shorthand properties are disabled. If desired, define your own aliases:

{
  "propertyAliases": {
    "p": "padding",
    "m": "margin",
    "bg": "background",
    "fs": "font-size"
  }
}

Then you can write:

component Card {
  p = 12
  bg = #111111
}

Invalid alias targets are ignored safely.

18) Node API Reference

import { compileStyleScript } from "stylescript-css";
import {
  compileStyleScriptFile,
  compileStyleScriptDirectory,
  compileStyleScriptBundleFromDirectory
} from "stylescript-css/node-api";

const result = compileStyleScript("component Button { padding = 12 }", {
  theme: "all",
  enforceMode: "error",
  propertyAliases: { p: "padding" }
});

await compileStyleScriptFile("src/styles/main.ss", "dist/css/main.css", {
  compatMode: "full",
  sourceMap: true
});

await compileStyleScriptDirectory("src/styles", "dist/css", {
  minify: true
});

await compileStyleScriptBundleFromDirectory("src/styles", "dist/css/style.css", {
  minify: true,
  compatMode: "full"
});

19) Error Messages and Debugging

Compiler errors include feature context and source location when possible.

Examples:

• type mismatch in typed variable
• missing theme token
• enforce rule violation
• parser syntax issue with code-frame diagnostics

If output is not as expected:

1. Build from the main entry file.
2. Verify @use / @forward paths.
3. Confirm theme token names exist.
4. Check custom propertyAliases values.

20) Best Practices

• Prefer full CSS property names for clarity (use aliases only if your team agrees).
• Keep one main.ss entry and compose via modules.
• Use nestedComponent for internal component parts.
• Use theme tokens instead of hardcoded colors.
• Enforce spacing/font/radius scales in config.
• Run audit regularly to remove dead styles.

21) Development

npm run check
npm run build
npm test

Version Notes

Current documented features include:

• advanced state selector support
• native-style aliases (motion, font, capable, adapt)
• intent layouts (hero, cards, stack)
• fluid typography helper (fluid(...))
• directional logical helpers (margin-start, padding-end, start, end)