teacss 0.4.6 → 0.5.0

package/README.md

@@ -1,364 +1,90 @@
 # TeaCSS
 
-**An LLM-friendly atomic CSS toolkit.**
+The application package for TeaCSS.
 
-Readable utilities for humans. Predictable syntax for AI agents.
+The root entry exports the official `cn`, `recipe`, `omitAttributes`,
+runtime types, and Standard constant tables. Engine and preset factories are
+available through explicit subpaths.
 
-## Purpose
+## Install
 
-`teacss` is the application-facing package. Its root entry provides the
-official `cn` and `recipe` runtime helpers, the `omitAttributes` attribute
-helper, and Standard preset constant tables, while its subpaths expose the
-engine and official presets.
+Install `teacss` as an application dependency and add the adapter for the
+project's build tool:
 
-Use it for normal TeaCSS applications. Preset authors, custom integration
-authors, and tooling authors should import the narrower `@teacss/*` packages
-that own those extension APIs; the root entry intentionally does not expose
-low-level factories such as `createReciper`.
+| Build tool     | Development packages            |
+| -------------- | ------------------------------- |
+| Vite           | `@teacss/vite vite`             |
+| Astro          | `@teacss/astro astro vite`      |
+| Rsbuild        | `@teacss/rsbuild @rsbuild/core` |
+| PostCSS        | `@teacss/postcss postcss`       |
+| Bun Build      | `@teacss/bun`                   |
+| Standalone CLI | `@teacss/cli`                   |
 
-The base installation contains the runtime class helpers, engine core, and
-official presets. Build integrations are separate packages, so install and
-import the one owned by the selected build boundary directly:
-
-Install the package names below as development dependencies with npm, pnpm,
-Yarn, or Bun. Bun Build itself requires the Bun runtime.
-
-| Build boundary | Development packages | Import |
-| --- | --- | --- |
-| Vite | `@teacss/vite vite` | `@teacss/vite` |
-| Astro | `@teacss/astro astro vite` | `@teacss/astro` |
-| Rsbuild | `@teacss/rsbuild @rsbuild/core` | `@teacss/rsbuild` |
-| PostCSS | `@teacss/postcss postcss` | `@teacss/postcss` |
-| Bun Build | `@teacss/bun` | `@teacss/bun` |
-
-The standalone CLI is intentionally separate because `teacss` has no CLI
-subpath or executable:
-
-Install `@teacss/cli` as a development dependency with the project's package
-manager.
-
-TeaCSS is an atomic CSS toolkit designed around a simple idea: utility classes should read like CSS declarations. Its primary audience is large language models, so every language and design tradeoff is judged first by whether a model can reliably predict the output. Instead of compressing meaning into short aliases, TeaCSS uses an explicit `property:value` syntax that remains easy for developers to read and easy for AI agents to generate, validate, and reason about. Predictability takes precedence over brevity.
-
-## Philosophy
-
-TeaCSS keeps three principles in view:
-
-* **Predictability over brevity.** A model should be able to infer the emitted CSS from the source token.
-* **Clarity over cleverness.** Classes should be readable first, compact only when that does not hide intent.
-* **One model over exceptions.** State, responsive behavior, relations, and arbitrary selectors all use the same trailing `@` condition axis. Write `p:4@hover`, never `hover:p:4`.
-
-## Usage
-
-Install or update the optional TeaCSS skill:
-
-```sh
-skills add teacss/skills --skill teacss
-skills update teacss
-```
-
-Restart Codex after installing the skill.
-
-Install the application package and the integration used by the project. For
-Vite, install `teacss` as an application dependency and `@teacss/vite` plus
-`vite` as development dependencies with npm, pnpm, Yarn, or Bun.
-
-Use the Vite integration:
+Example with Vite:
 
 ```ts
+import { defineConfig } from "vite";
 import { pluginTeacss } from "@teacss/vite";
 
-export default {
-  plugins: [pluginTeacss()],
-};
+export default defineConfig({ plugins: [pluginTeacss()] });
 ```
 
-Create a TeaCSS entry at `index.css` or `src/index.css`:
-
 ```css
 @preset "standard";
-@source "./src/**/*.{ts,tsx}";
+@source "./src/**/*.{ts,tsx,html}";
 @teacss;
 ```
 
-Add `@preset "icons";` when the app uses the official icon vocabulary.
-Add `@preset "articles";` for the fixed semantic-descendant utility
-`article:base`:
-
-```html
-<article
-  class="article:base max-inline-size:65ch m-a:auto font-size:3x text-color:$color-foreground"
->
-  <h1>Title</h1>
-  <p>Readable long-form content.</p>
-</article>
-```
-
-The utility defaults to TeaCSS's shared `shortcuts` layer
-(`LAYER_SHORTCUTS`). Under the default layer order, ordinary utilities in the
-`utilities` layer emit later. The preset does not create an article-specific
-layer.
-
-The articles factory is available only from its explicit subpath:
-
-```ts
-import presetArticles, { presetArticles as namedPresetArticles } from "teacss/preset-articles";
-```
-
-The root `teacss` entry does not re-export it.
-
-Import the generated stylesheet once from your app entry:
-
 ```ts
 import "virtual:teacss.css";
 ```
 
-Then write TeaCSS utilities in your markup:
-
-```html
-<button class="p:4 bg-color:red-500 text-color:white bg-color:red-600@hover">
-  Submit
-</button>
-```
+## Presets
 
-The root entry also re-exports the Standard preset's constant tables for
-programmatic use:
+Enable optional vocabularies explicitly:
 
-```ts
-import { breakpointKeywords, primaryColors } from "teacss";
+```css
+@preset "standard";
+@preset "shortcuts";
+@preset "icons";
 ```
 
-These are the same exports as `@teacss/preset-standard/constants`; there is no
-separate `teacss/constants` subpath.
+Shortcuts includes `prose`, `prose-hans` and `prose-hant` for long-form content;
+the separate Articles preset is retired. Shortcuts does not enable Standard. All preset factories are available from
+subpaths:
 
-Grouped utilities can share the same condition:
-
-```html
-<button class="{p:4;text-color:white;bg-color:red-500}@hover">
-  Submit
-</button>
-```
+| Import                    | Export              |
+| ------------------------- | ------------------- |
+| `teacss/preset-standard`  | `presetStandard`    |
+| `teacss/preset-shortcuts` | `presetShortcuts`   |
+| `teacss/preset-icons`     | `presetIcons`       |
+| `teacss/core`             | Core engine exports |
 
-## Runtime Recipes
-
-The application entry exports `recipe`, bound once to its exact official
-`cn`:
+## Runtime classes
 
 ```ts
-import { recipe, type ClassProp, type VariantProps } from "teacss";
+import { cn, recipe, type ClassProp, type VariantProps } from "teacss";
+
+cn("p:4 d:flex", "p:8"); // "d:flex p:8"
 
 const badge = recipe({
-  className: "d:inline-flex align-items:center rd:full p-x:2",
+  className: "d:inline-flex p:2",
   variants: {
-    tone: {
-      neutral: "bg-color:gray-100 text-color:gray-900",
-      accent: "bg-color:blue-500 text-color:white",
-    },
+    tone: { accent: "bg-color:blue-500 text-color:white" },
   },
-  compoundVariants: [
-    {
-      tone: "accent",
-      className: "font-weight:700",
-    },
-  ],
 });
 
-badge({
-  tone: "accent",
-  className: "p-x:3",
-}); // string
-
 type BadgeProps = VariantProps<typeof badge> & ClassProp;
-
-function badgeClassName({ className, ...variants }: BadgeProps) {
-  return badge({ ...variants, className });
-}
-```
-
-A primitive string top-level `className` value selects the single-element form.
-Its variant choices and compound outputs are strings; the recipe call accepts
-variants plus caller `className` and returns the merged string directly.
-
-Use a non-empty object top-level `className` value for multiple elements:
-
-```ts
-const button = recipe({
-  className: {
-    container: "d:inline-flex align-items:center p:2 p:4@md",
-    icon: "inline-size:4x",
-  },
-  variants: {
-    size: {
-      small: {
-        container: "p:2",
-        icon: "inline-size:3x",
-      },
-      large: {
-        container: "p:4",
-        icon: "inline-size:5x",
-      },
-    },
-    disabled: {
-      true: {
-        container: "opacity:50 pointer-events:none",
-      },
-    },
-  },
-  defaultVariants: {
-    size: "small",
-    disabled: false,
-  },
-  compoundVariants: [
-    {
-      size: "large",
-      disabled: true,
-      className: {
-        container: "font-weight:700",
-        icon: "inline-size:6x",
-      },
-    },
-    {
-      disabled: true,
-      classKeys: ["container", "icon"],
-      className: "opacity:80",
-    },
-  ],
-});
-
-const classes = button({
-  size: "large",
-});
-
-classes.container({
-  disabled: true,
-  className: "p:6",
-});
-classes.icon();
-
-type ButtonProps = VariantProps<typeof button> & ClassProp;
-
-function buttonClassName({ className, ...variants }: ButtonProps) {
-  return button(variants).container({ className });
-}
 ```
 
-There is no distinguished or required `root` key in an object-form top-level
-`className`; every declared key is an ordinary named class. Variant choices are
-always target maps. A compound either supplies a non-empty `className` target
-map, or pairs a primitive-string `className` with a non-empty `classKeys` array
-to broadcast that class to several effective named classes. `classKeys` may
-name declared or inherited classes and must be dense, unique, and free of
-unknown names. The two compound forms are mutually exclusive, and matching
-entries contribute in declaration order. A recipe call returns a readonly
-resolver for every name.
-Recipe-level selections are captured once. A resolver selection is local to
-that invocation, compounds are re-evaluated for it, and `className` appends only
-to that resolver. The one-sided `"true"` choice makes `disabled`
-boolean-capable: boolean `false` is a branchless state that contributes no
-fragment but can still drive defaults and compounds. Responsive behavior
-remains suffix-only inside static values, such as `p:4@md`; recipe props do not
-accept breakpoint objects.
-
-Every definition without `extend` requires its own `className` field. An
-extending child may omit `className` to inherit the parent's string or object
-mode, base fragments, and existing named classes. If a child declares
-`className`, it must keep that mode; an object child may add new names:
-
-```ts
-const primaryButton = recipe({
-  extend: button,
-  variants: {
-    emphasis: {
-      strong: {
-        container: "font-weight:700",
-      },
-    },
-  },
-});
-
-const strongBadge = recipe({
-  extend: badge,
-  className: "font-weight:700",
-});
-```
-
-`classKeys` is reserved as a variant name, while `parts`, `styles`, and
-`styleKeys` are available as ordinary variant names. Nested
-`compoundVariants[].classKeys` is supported; the retired top-level definition
-field `styles` and former nested `parts` selector are not compatibility aliases.
-
-The repeated `className` spelling is separated by boundary:
-`definition.className` supplies base classes and selects string or object mode,
-`compoundVariants[].className` supplies a compound output, and caller
-`className` is accepted by a single-element recipe call or one named resolver.
-A multi-element recipe call itself accepts shared selections only.
-
-`@teacss/classes` exports the factory rather than a pre-bound reciper. This
-integration creates its own `recipe` from the official `cn`; custom
-integrations follow the same boundary with their own merger:
-
-```ts
-import { createReciper, createMerger } from "@teacss/classes";
-
-const merge = createMerger({ conflicts, plugins });
-export const recipe = createReciper({ merge });
-```
-
-`createReciper` and its type-only `Reciper` return type are intentionally
-available only from `@teacss/classes`; the named return type keeps declarations
-for exported integration-owned recipers compact. Normal recipe libraries
-peer-depend on and externalize `teacss`. A custom integration peer-depends on
-`@teacss/classes` and exports the exact reciper used for extendable parents.
-Consumers deduplicate the owning integration. Recreating a reciper, loading
-another runtime copy or version, or resolving the parent and reciper from
-different provider-package instances breaks extension identity even if the
-declarations and merger are compatible. Deduplicating only `@teacss/classes`
-is insufficient for a duplicated custom-reciper provider. `VariantProps`
-extraction does not need runtime identity; `extend` does.
-
-## Runtime Class Merging
-
-Use the application runtime merger for component class names. It understands the
-standard vocabulary and canonical `icon:<collection>-<icon-name>` utilities:
-
-```ts
-import { cn } from "teacss";
-
-cn("p:4 d:flex", "p:8"); // "d:flex p:8"
-cn("p:4", "p:invalid"); // "p:invalid"
-cn("reset-list", "reset-heading"); // "reset-heading"
-cn("d:block", "reset-list"); // "d:block reset-list"
-```
-
-The default `cn` is one direct merger composed from `pluginStandard` and
-`pluginIcon`; it does not chain preset-local mergers. Resolution is based
-on parsed shape, conditions, importance, and declared footprints. It does not
-validate values, so an unsupported winner may emit no CSS. The eight reset
-profiles apply to the current element and are bare class names, never
-`property:value` utilities: `reset-heading`, `reset-list`, `reset-button`,
-`reset-select`, `reset-textarea`, `reset-input`, `reset-checkbox`, and
-`reset-radio`. `reset-input` is only for text-like inputs; button-like input
-types use `reset-button`, and box controls take `reset-checkbox` /
-`reset-radio`.
-Element deltas expressible with ordinary utilities carry no profile — use
-`text-color:inherit decoration-line:none` for a link and
-`d:block text-align:unset` for a list item. Profiles replace one another as a
-single opaque family and never delete an unrelated utility. Document-root and shadow-host
-defaults come from the standard preset's automatic preflight.
-
-Generic class merging is a separate package for custom conflict metadata:
-
-Install `@teacss/classes` with the project's package manager.
-
-```ts
-import { createMerger } from "@teacss/classes";
-```
-
-## Status
-
-TeaCSS is currently pre-1.0 and under active development.
+`cn` understands Standard and canonical icon conflicts but does not validate
+values. `recipe` supports string or named-element `className` definitions,
+variants, compounds, and exact-reciper extension. Import low-level factories
+such as `createMerger` and `createReciper` from `@teacss/classes`.
 
-Syntax, configuration, package boundaries, and public APIs may change before the first stable release.
+Standard constant tables are re-exported from the root; there is no
+`teacss/constants` subpath.
 
-## License
+Pre-1.0. Syntax, configuration, and APIs may change before the stable release.
 
-MIT. See [LICENSE](LICENSE).
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ClassProp, Merger, RecipeIntrospection, Reciper, VariantProps, omitAttributes } from "@teacss/classes";
 export * from "@teacss/preset-standard/constants";
 //#region src/index.d.ts
-declare const cn: Merger;
-declare const recipe: Reciper;
+export declare const cn: Merger;
+export declare const recipe: Reciper;
 //#endregion
-export { type ClassProp, type RecipeIntrospection, type VariantProps, cn, omitAttributes, recipe };
+export { type ClassProp, type RecipeIntrospection, type VariantProps, omitAttributes };

package/dist/preset-shortcuts.d.ts

@@ -0,0 +1,3 @@
+import preset_shortcuts_default from "@teacss/preset-shortcuts";
+export * from "@teacss/preset-shortcuts";
+export { preset_shortcuts_default as default };

package/dist/preset-shortcuts.js

@@ -0,0 +1 @@
+import e from"@teacss/preset-shortcuts";export*from"@teacss/preset-shortcuts";export{e as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teacss",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "The TeaCSS application entry with the official `cn`, `recipe`, engine, and preset subpaths.",
   "homepage": "https://css.teasim.com",
   "funding": "https://github.com/sponsors/billgo",
@@ -11,8 +11,8 @@
   "exports": {
     ".": "./dist/index.js",
     "./core": "./dist/core.js",
-    "./preset-articles": "./dist/preset-articles.js",
     "./preset-icons": "./dist/preset-icons.js",
+    "./preset-shortcuts": "./dist/preset-shortcuts.js",
     "./preset-standard": "./dist/preset-standard.js",
     "./package.json": "./package.json"
   },
@@ -26,11 +26,11 @@
     "dev": "tsdown --watch"
   },
   "dependencies": {
-    "@teacss/classes": "0.4.6",
-    "@teacss/core": "0.4.6",
-    "@teacss/preset-articles": "0.4.6",
-    "@teacss/preset-icons": "0.4.6",
-    "@teacss/preset-standard": "0.4.6"
+    "@teacss/classes": "0.5.0",
+    "@teacss/core": "0.5.0",
+    "@teacss/preset-icons": "0.5.0",
+    "@teacss/preset-shortcuts": "0.5.0",
+    "@teacss/preset-standard": "0.5.0"
   },
   "engines": {
     "node": ">=22.12.0"

package/dist/preset-articles.d.ts

@@ -1,3 +0,0 @@
-import preset_articles_default from "@teacss/preset-articles";
-export * from "@teacss/preset-articles";
-export { preset_articles_default as default };

package/dist/preset-articles.js

@@ -1 +0,0 @@
-import e from"@teacss/preset-articles";export*from"@teacss/preset-articles";export{e as default};