Skip to content

AGENTS.md

Latest commit

 

History

History
153 lines (132 loc) · 6.76 KB

AGENTS.md

File metadata and controls

153 lines (132 loc) · 6.76 KB
Raw

Agent Guide

Read this first, then read architecture.md for the detailed system map. Keep this file focused on day-to-day orientation for agents; put durable architecture details in architecture.md.

CSSX is the CSS toolchain used by StartupJS and usable on its own. Users write css, styl, and optional pug templates with styleName and part props. Babel compiles that authoring syntax into CSSX sheet IR plus runtime calls. The unified @cssxjs/css-to-rn package owns CSS parsing, selector matching, CSS variable resolution, CSS value evaluation, React Native/web style transforms, runtime caching, provider themes, custom media, dimensions, and React subscriptions.

Start Here

  1. Read architecture.md before changing cross-package behavior.
  2. Read docs/guide/index.md, docs/guide/usage.md, docs/guide/component-parts.md, docs/guide/variables.md, docs/guide/theming.md, and docs/examples/theme.md for the public model.
  3. Use the package map below to choose the smallest code area to edit.
  4. Check plan.md only for future/backlog items. Completed architecture should live in architecture.md, not in plan.md.

Package Map

  • packages/css-to-rn/: unified compiler/runtime engine. Start here for CSS parsing, selector IR, value resolution, color functions, property transforms, caching, cssx(), useRuntimeCss(), variables, dimensions, provider themes, custom media, and React tracking.
  • packages/cssxjs/: public cssxjs facade, package exports, CLI, runtime compatibility wrappers, Babel preset wrapper, loader wrappers, Metro wrappers, and built-in theme entrypoints such as cssxjs/themes/tailwind and cssxjs/themes/shadcn.
  • packages/loaders/: Stylus/CSS loaders and direct compiler wrappers. Pure CSS compilation delegates to @cssxjs/css-to-rn; Stylus remains a separate preprocessing step.
  • packages/babel-plugin-rn-stylename-inline/: compiles inline css and styl templates, including local template interpolation lowering.
  • packages/babel-plugin-rn-stylename-to-style/: rewrites JSX styleName, part, legacy *StyleName, imported style sheets, and helper calls into runtime calls.
  • packages/babel-preset-cssxjs/: transform ordering and public Babel options.
  • packages/bundler/: Metro hot-reload path for separate style files.
  • packages/eslint-plugin-cssxjs/: wrapper around the React Pug ESLint processor.
  • docs/: user-facing docs; update these when public behavior changes.
  • example/: web demo using Babel plus esbuild.

Core Contracts

  • __CSS_GLOBAL__ and __CSS_LOCAL__ connect the inline Babel plugin to the JSX/runtime plugin.
  • Runtime calls generated by Babel keep the compatibility shape runtime(styleName, fileStyles, globalStyles, localStyles, inlineStyleProps).
  • cssxjs/runtime/* wrappers adapt that call shape to the platform entrypoints exported by @cssxjs/css-to-rn.
  • Style priority is outer provider layers, inner provider layers, file/imported sheets, global templates, local templates, then inline props. Matching rules also sort by specificity and source order.
  • Compiled sheets are JSON-serializable IR. Runtime cache, subscriptions, and dependency tracking must stay outside the sheet.
  • part='root' maps to style; other parts map to {partName}Style.
  • :hover, :active, :part(hover), and :part(active) compile to hoverStyle and activeStyle.
  • Component tag selectors such as Button and Button:part(text) apply only inside components wrapped with themed('Button', Component) or an explicit resolver tag option.
  • Provider/global :root custom properties compile to sheet.rootVariables. Theme variables use :root.<theme>, for example :root.dark.
  • CssxProvider layers provider styles, root variables, custom media, and the active theme. At the root, no theme prop uses the persisted global preference, or default when no preference exists. Root theme='auto' uses the system color scheme as the initial preference, then saved/user-selected preference takes priority.
  • CSSX reserves custom media names matching --theme-*. @media (--theme-dark) is the standard way to write theme-specific rules.
  • @custom-media --name (...) is supported in provider and component CSS. StartupJS UI uses breakpoint aliases such as --breakpoint-tablet.
  • variables and defaultVariables are validating proxies. Direct assignment/deletion works for valid --name keys; bulk updates use .assign(), .set(), and .clear().
  • Local JS template interpolation is lowered to synthetic var(--__cssx_dynamic_N) slots and passed as values.
  • Runtime CSS uses useRuntimeCss(rawCss) plus cssx(styleName, sheet, inlineStyleProps) for dynamic client-side compilation. Variables come from variables, defaultVariables, provider :root, or template/layer values.
  • getCssColor() and useCssColor() bridge CSS variables/colors into JS and return React Native-friendly values.
  • useMedia() bridges CSSX custom media/media-query evaluation into JS.
  • cache: 'teamplay' remains accepted as a Babel option for compatibility, but runtime caching is owned by @cssxjs/css-to-rn, not Teamplay.

Commands

Install dependencies:

yarn install

Run all package tests:

yarn test

Run targeted tests:

cd packages/css-to-rn && npm test
cd packages/css-to-rn && npm run test:types
cd packages/babel-plugin-rn-stylename-inline && yarn test
cd packages/babel-plugin-rn-stylename-to-style && yarn test
cd packages/loaders && yarn test
cd packages/cssxjs && npm test

Run docs locally:

yarn docs

Run the example app:

yarn start

Change Guidance

  • Treat AGENTS.md and architecture.md as living onboarding docs. If your change alters package boundaries, public APIs, build/runtime flow, commands, testing expectations, or maintenance rules, update these files in the same change before handing work back.
  • For CSS parsing, selector, value, transform, cache, variable, media, theme, or React tracking behavior, update packages/css-to-rn/test/engine/** or packages/css-to-rn/test/react/**.
  • For inline template or interpolation compilation, update packages/babel-plugin-rn-stylename-inline snapshots.
  • For JSX styleName/part behavior, update packages/babel-plugin-rn-stylename-to-style snapshots.
  • For public exports or wrapper behavior, update packages/cssxjs smoke tests.
  • For public API or behavior changes, update docs/, architecture.md, and this guide.
  • For Pug, type checking, or ESLint behavior, check whether the implementation lives in @react-pug/*; this repo often only wraps it.
  • For separate style files, check both Babel compileCssImports behavior and Metro transformer behavior.
  • Prefer current source code and docs/ over older package READMEs when they conflict.