Skip to content

feat: Move StartupJS UI theme system to CSSX#41

Merged
cray0000 merged 64 commits into
alphafrom
cssx-theme-migration
Jun 24, 2026
Merged

feat: Move StartupJS UI theme system to CSSX#41
cray0000 merged 64 commits into
alphafrom
cssx-theme-migration

Conversation

@cray0000

@cray0000 cray0000 commented Jun 21, 2026

Copy link
Copy Markdown
Member

Summary

  • migrate StartupJS UI to the CSSX-first theme model backed by CSS variables, component tag selectors, and :part() overrides
  • compose UiProvider from CSSX Tailwind tokens, CSSX shadcn semantic tokens, and startupjsUiTheme.cssx.css, with app-provided StartupjsProvider style layered after UI defaults
  • replace the old palette/Colors/CssVariables theme runtime with normal CSSX :root variables and semantic --color-* tokens
  • remove public useThemeColor(), getThemeColor(), getThemeColorVariableName(), Colors, Palette, CssVariables, generateColors, and useColors APIs
  • keep @startupjs-ui/core as a tiny non-style package for the UIRole type only
  • refactor component JS color reads to CSSX useCssColor() / useCssVariable() primitives re-exported from startupjs
  • inline all component, demo, MDX renderer, and docs styles into local css templates; only the package-level startupjsUiTheme.cssx.css theme asset remains
  • replace Stylus helpers, $UI, u, :export config, and separate .cssx.styl files with CSS variables, rem, color-mix(), oklch(), and CSSX custom media
  • preserve component customization through themed(name, Component), component tag selectors, semantic part props, and per-instance style / *Style props
  • update documentation to present StartupjsProvider style, CSSX tokens, tag overrides, and :part() as the customization model
  • keep the generic Styling guide as the canonical theming doc while component pages document only their own parts and variables/defaults
  • memoize the UI provider style layer array so provider context does not churn when style is unchanged
  • improve generated part reference extraction for conditional part arrays such as TextInput icon parts

Why

CSSX now owns provider-scoped :root variables, global utility classes, component tag selectors, :part() / ::part() overrides, subscribed CSS variable reads, OKLCH evaluation, and color-mix(). Keeping palette generation, theme-color hooks, theme context, component override wiring, or style helpers inside startupjs-ui would duplicate that model and keep theming in the wrong layer.

With this change, the StartupJS UI theme is normal CSSX CSS:

:root {
  --color-primary: oklch(0.55 0.22 260);
  --Button-radius: var(--radius-md);
}

Button {
  border-radius: 12px;
}

Button:part(text) {
  color: var(--color-primary-foreground);
}

Component color props still accept tokens such as primary, which map to --color-primary. Raw CSS values and var(--x) remain valid where component props accept raw colors.

Related PRs

Validation

  • node scripts/update-style-reference-docs.mjs idempotency check
  • yarn generate-package-dts
  • node scripts/check-startupjs-ui-exports.mjs
  • yarn build for the docs app
  • git diff --check
  • CSSX docs/provider smoke with local source links:
    • generic /docs/Styling theming guide renders and remains the canonical styling model doc
    • /docs/TextInput renders and includes conditional inputIconLeft / inputIconRight parts
    • component docs for Button, Item, Div, and DateTimePicker render their generated Styling reference sections
    • component reference sections list parts and component-specific variables/defaults and link back to the generic Styling guide
    • no unknown CSS color token warnings or page errors observed
  • Storybook runtime smoke through http://localhost:4400/iframe.html:
    • Introduction/Overview
    • Actions/Button
    • Data/Item
    • Display/Badge
    • Feedback/Modal
    • Overlay/Popover
    • System/StartupJS UI
    • Inputs/TextInput
    • Inputs/DateTimePicker
  • Visual screenshots checked for Styling, Button, Item, DateTimePicker, provider, and popover pages/stories.
  • Known during DateTimePicker smoke: Moment Timezone logs its existing missing timezone-data warning; no CSS token, page, or provider errors were observed.
  • Previous validation in this draft also included yarn install --immutable --mode=skip-build, targeted eslint over migrated packages/docs slices, and direct CSS-template compile smoke over packages/ plus startupjsUiTheme.cssx.css.

Review Focus

  • token naming and override surface in startupjsUiTheme.cssx.css
  • remaining public API compatibility that should intentionally stay or be removed for the breaking release
  • part coverage on roots and semantically useful sub-elements
  • JS-only color bridge usage where CSS variables could replace code
  • docs clarity around StartupjsProvider style, CSSX variables, component tag selectors, and :part() overrides

@cray0000 cray0000 changed the title Use CSSX runtime for theme styles Move StartupJS UI theme system to CSSX Jun 21, 2026
@cray0000 cray0000 marked this pull request as ready for review June 24, 2026 02:30
cray0000 added a commit to startupjs/cssx that referenced this pull request Jun 24, 2026
## Summary

This PR unifies the CSS-to-React-Native style pipeline into a new
`@cssxjs/css-to-rn` workspace package and wires CSSX, loaders, Babel
output, and runtime entrypoints through it. The goal is to replace the
separate forked CSS-to-RN transform libraries and the old CSSX runtime
with one maintainable compiler/runtime package.

Key changes:

- Adds `packages/css-to-rn`, a TypeScript ESM package owning CSS
parsing, selector IR, value resolution, property transforms, style
resolution, caching, and React runtime tracking.
- Keeps Stylus-to-CSS compilation separate, while moving pure CSS-to-RN
style compilation and runtime resolution into the unified package.
- Supports local JS template interpolation in function-scoped
`css`/`styl` templates, with interpolation values reusing one cache slot
per compiled call shape.
- Adds runtime CSS string compilation for generated CSS via
`useRuntimeCss()`, `useCssxLayer()`, and `cssx()`.
- Implements nested `var()` resolution, partial shorthand substitution,
dynamic dependency tracking, bounded cache behavior, deep inline-style
hashing, media/dimension tracking, web `matchMedia` invalidation, and
React Native `Dimensions` integration.
- Adds React 19 tracking without Teamplay or `@nx-js/observer-util`,
including Suspense/aborted-render cleanup tests.
- Adds `CssxProvider style` and `theme` for subtree-scoped provider CSS,
global utility classes, scoped `:root` / `:root.<theme>` variables, OS
dark-mode auto selection, and component tag overrides.
- Adds CSSX theme assets and exports: `cssxjs/themes/tailwind` and
`cssxjs/themes/shadcn`.
- Adds `@custom-media`, CSS media range evaluation for width/height
comparisons, built-in `@media (--theme-*)` aliases, and provider-aware
`useMedia()`.
- Adds component tag selectors through `themed(tagName, Component)`,
including `Tag`, `Tag.class`, `Tag:part(name)`, `Tag::part(name)`,
`Tag:hover`, and `Tag:active` matching.
- Adds `useCssVariable()`, `useCssVariableRaw()`, `getCssVariable()`,
and `getCssVariableRaw()` for subscribed and global JS access to
resolved CSS variables.
- Adds `useCssColor()` and `getCssColor()` for provider-aware JS color
bridges, including token lookup and `color-mix()` style mixing.
- Adds a deprecated JS `u()` helper and build diagnostics for deprecated
CSS `u` units.
- Adds validating `variables` and `defaultVariables` proxy methods:
`.assign()`, `.set()`, and `.clear()`.
- Resolves `var()` inside inline style props and tracks the variables
used by those inline props.
- Normalizes `oklch()`, `oklab()`, and `color-mix()` through pinned
`@colordx/core@5.4.3` so modern color CSS works on RN.
- Supports percentage/unitless `calc()` in CSS value resolution for
color-channel math while still rejecting mixed layout calc such as
`calc(100% - 16px)`.
- Mixes `color-mix(in srgb, color, transparent)` with premultiplied
alpha so transparent theme colors preserve the source RGB.
- Preserves source-condition TypeScript consumers without committing
build output: source entrypoints carry vendor shims, `themed()`
preserves wrapped component props, and `cssx()` accepts loader-produced
opaque sheet records at the type boundary.
- Implements `:hover`/`:active` aliases, `filter`,
`background-image`/gradient support, limited `background` shorthand,
animations/transitions/keyframes, and Reanimated v4-compatible animation
style output.
- Adds build-strict diagnostics for unsupported static declarations
while keeping runtime compilation graceful for generated CSS.
- Migrates loaders and Babel runtime paths to the unified package, with
source-condition test/dev imports and facade smoke coverage.
- Stops tracking generated `dist` output; package builds still emit
`dist` for published/default exports.
- Keeps legacy `runtime/*-teamplay` import paths as compatibility
wrappers only.
- Removes the old `packages/runtime` package from the active graph.
- Updates `architecture.md`, `AGENTS.md`, `plan.md`, public docs, README
credits, and CI smoke checks for the new architecture.

## Architect Review Follow-up

After a multi-agent architecture/performance/test-coverage review, this
PR now also:

- avoids promoting changed tracked sheets, interpolation values, or hook
dependencies from Suspense-aborted renders
- keeps `useCssxLayer(false)` hook order stable when toggled to a real
sheet
- allows and resolves template interpolation inside provider `:root`
custom property values
- resolves provider root variables from compiled sheets and `{ sheet,
values }` layers
- adds regression coverage for complex partial `var()` values in
box-shadow/filter/text-shadow/transform/background
- updates runtime docs for precompiled provider `:root` interpolation
- maps `:part(root)` to the root `style` prop consistently in the
unified resolver
- expands `@custom-media` subscriptions to concrete media dependencies
and marks width/height range queries as dimension-dependent
- surfaces runtime sheet compile diagnostics through `resolveCssx()` for
generated CSS callers
- keeps `cssxjs/runtime/web` and `cssxjs/runtime/react-native` exporting
the public CSSX/color helpers with smoke coverage

## Related PRs

- startupjs/startupjs#1327 wires `StartupjsProvider style` and `theme`
into CSSX so framework users can pass provider CSS and theme selection
through the StartupJS root provider.
- startupjs/startupjs-ui#41 moves StartupJS UI theming onto CSSX theme
assets, `startupjsUiTheme.cssx.css`, CSS variable primitives, and direct
component tag/part overrides.

## Validation

- `cd packages/css-to-rn && npm test`
- `cd packages/babel-plugin-rn-stylename-inline && yarn test`
- `cd packages/babel-plugin-rn-stylename-to-style && yarn test`
- `git diff --check`
- `cd packages/cssxjs && yarn test`
- CSSX theme entrypoints compile through JS import/default-export
wrappers instead of leaking `.cssx.css` assets into consuming web
builds.
- Cross-repo StartupJS UI validation with local source links:
  - `node scripts/update-style-reference-docs.mjs` idempotency check
  - `yarn generate-package-dts`
  - `node scripts/check-startupjs-ui-exports.mjs`
  - `yarn build` for startupjs-ui docs
- Playwright smoke for the generic Styling guide plus Button, Item, Div,
and DateTimePicker docs pages
- Playwright smoke for Storybook iframe stories: Overview, Button, Item,
Badge, Modal, Popover, System/StartupJS UI, and DateTimePicker
- visual screenshots checked for Styling, Button, Item, DateTimePicker,
provider, and popover stories
- Known during DateTimePicker smoke: Moment Timezone logs its existing
missing timezone-data warning; no CSS token, page, or provider errors
were observed.
- startupjs PR validation: `NODE_OPTIONS="-C cssx-ts" npm test` in
`core/startupjs`, plus the normal pre-commit hook with eslint and `npx
startupjs check`.

## Review Focus

This is a large architectural PR. Please scrutinize:

- Runtime cache invalidation, interpolation cache behavior, and
reference stability.
- Provider `:root` / `:root.<theme>` variable scoping and precedence
relative to runtime/default variables.
- Theme selection, OS color-scheme subscriptions, and `@media
(--theme-*)` behavior.
- `@custom-media`, range media evaluation, and `useMedia()`
subscriptions.
- Component tag selector matching and the `themed()` render-local
tracking model.
- `useCssVariable()` / `useCssColor()` exact subscriptions and
Suspense/aborted-render safety.
- Media/dimension invalidation, web `matchMedia` subscriptions, React
Native dimensions, and listener cleanup.
- Complex value parsing: nested `var()`, shorthand fragments, modern
colors, gradients/backgrounds, transforms, animations, transitions, and
invalid generated CSS.
- Babel output compatibility with existing CSSX `styleName`, `css`,
`styl`, and part workflows.
- Package exports/source-condition behavior and whether the new package
boundary is maintainable long term.
cray0000 added a commit to startupjs/startupjs that referenced this pull request Jun 24, 2026
## Summary

- wrap `StartupjsProvider` children in CSSX `CssxProvider`
- pass `StartupjsProvider style` into CSSX and through the existing
plugin `renderRoot` hook
- pass `StartupjsProvider theme` into CSSX so apps can select `auto`,
`default`, `light`, `dark`, or custom CSSX themes from the framework
root
- add a `.d.ts` surface for `StartupjsProvider`, including CSSX provider
style and theme inputs
- re-export CSSX theme assets from `startupjs/themes/tailwind` and
`startupjs/themes/shadcn`

## Why

The CSS-first UI theme migration needs framework users to configure
global CSSX variables, utility classes, component tag overrides, and
theme selection through the normal StartupJS root provider. Direct CSSX
users can still use `CssxProvider` themselves; StartupJS users can pass
the same style and theme inputs to `StartupjsProvider`.

Bare StartupJS still does not include Tailwind, shadcn, or StartupJS UI
theme styles by default. Those are included by startupjs-ui when its
plugin injects the UI provider.

## Related PRs

- startupjs/cssx#5 adds the unified CSSX compiler/runtime,
`CssxProvider`, provider-scoped `:root`, tag selectors, CSS variable
hooks, OKLCH/color-mix evaluation, custom media, theme assets, and
runtime CSS support.
- startupjs/startupjs-ui#41 moves the UI theme system onto CSSX theme
assets, `startupjsUiTheme.cssx.css`, direct CSS variable primitives, and
component tag/part overrides.

## Validation

- `NODE_OPTIONS="-C cssx-ts" npm test` in `core/startupjs`
- normal pre-commit hook, including eslint and `npx startupjs check`
@cray0000 cray0000 changed the base branch from master to alpha June 24, 2026 14:33
@cray0000 cray0000 changed the title Move StartupJS UI theme system to CSSX feat: Move StartupJS UI theme system to CSSX Jun 24, 2026
@cray0000 cray0000 merged commit 3f1e4b9 into alpha Jun 24, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant