Skip to content

docs: define component style authoring architecture - #6129

Merged
cixzhang merged 2 commits into
mainfrom
spec-component-style-authoring
Sep 8, 2026
Merged

cixzhang merged 2 commits into
mainfrom
spec-component-style-authoring

Conversation

@cixzhang

@cixzhang cixzhang commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

Summary

  • defines five observable component-style authoring invariants: StyleX lowering, CSS-over-JS presentation ownership, valid static composability, scoped relational state, and named wrapper responsibility
  • keeps exact StyleX capabilities, shorthand/reset/null syntax, helper names, and lint matchers as versioned guidance/tooling rather than permanent architecture vocabulary
  • permits component-owned non-glyph inline SVG while delegating semantic glyphs to icon authority
  • permits wrappers for semantics, behavior/ref, formatting contexts, outside-border spacing, or a required style-bearing DOM boundary when the child has no compatible surface
  • delegates tokens, theming axes/targets, BaseProps/public styling, RTL, and RSC module boundaries to their canonical owners

Audit-row coverage

Owned here:

  • Q6 / T14 — wrapper responsibility
  • durable composability outcome behind Q7
  • T8 — StyleX lowering and CSS-over-JS ownership
  • valid-lowering outcome behind T9
  • T10 — CSS-over-JS ownership
  • T11 — relational-state isolation

Delegated:

  • Q4 / T17 / T18 → icon architecture, Icon contract, and theme authoring
  • T2b → theme-token architecture
  • T13 → future current bidirectionality owner
  • T19 / T27 → component-theming-surface; T19 reachability also uses public-component-api
  • T20 → public-component-api
  • T30 → future current RSC/module-boundary owner

Owner assumptions

  • Inline SVG is prohibited only when it shadows a registry-owned glyph; component-owned non-glyph vectors remain allowed.
  • A wrapper needs a named runtime responsibility; source clarity alone is not normative.

Overlap receipt

False-positive / false-negative audit

Initial bounded current-code matrix: 12 correct, 1 false-positive risk, 1 false-negative risk, 2 untestable.

After exact fixes for child style-bearing surfaces, component-local raw CSS, and StyleX registry/package version drift: 11 correct, 0 false positives, 0 false negatives, 5 intentionally untestable capability-dependent cases across the same 16 cases. Untestable cases require matching the capability registry's recorded StyleX version to the installed package.

Validation

  • node scripts/check-knowledge.mjs
  • pnpm check:sync
  • Prettier
  • git diff --check
  • independent authority map, Matt-style challenge, and exact-file current-code FP/FN audit

No implementation, tooling, lint, wiki, or audit-table changes. No changeset.

@vercel

vercel Bot commented Sep 7, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Sep 8, 2026 12:27am UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Sep 7, 2026
github-actions Bot added a commit that referenced this pull request Sep 7, 2026
@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

No component packages changed.

Accessibility Audit

Status: No accessibility violations detected.


Generated by PR Enrichment workflow | Storybook | Sandbox | View full report

@cixzhang
cixzhang force-pushed the spec-component-style-authoring branch from 7094580 to 55d4568 Compare September 8, 2026 00:23
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Sep 8, 2026
@cixzhang

cixzhang commented Sep 8, 2026

Copy link
Copy Markdown
Contributor Author

/approve-spec 55d4568

@cixzhang
cixzhang marked this pull request as ready for review September 8, 2026 00:25
@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Sep 8, 2026
github-actions Bot added a commit that referenced this pull request Sep 8, 2026

@cixzhang cixzhang left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Semantic verdict: request changes

Thanks — the authority boundaries are clear. I think the verification contract needs one more pass before this becomes current. The relational scanner only compiles through the global default marker, so it never proves nested-owner isolation. The wrapper rule also recommends xstyle for any relative import without proving the child has a compatible style-bearing surface.

Could we either add the scoped-marker/nested-owner and incompatible-child fixtures the Verification table names, or label those rows as current verification gaps?

[Reviewed by Robohands]

@cixzhang
cixzhang merged commit 5b3ebfc into main Sep 8, 2026
34 checks passed
@github-actions
github-actions Bot deleted the spec-component-style-authoring branch September 8, 2026 06:22

This branch was successfully deployed

1 active deployment
Preview — 55d45684 Deployed Sep 8, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant