feat(fields): build and publish the style.css the package has always declared (#4059)

[yinlianghui]

Fixes #4059

Implements Delegated Ruling #2 (comment): route B, narrow variant, after ruling #1's premise was measured and falsified.

Why this route

Ruling #1 was "retire the phantom export", premised on fields' class shapes being a subset of @object-ui/components' published utilities. Measured first, that premise is false — so removal would have ratified a permanently under-styled package rather than costing nothing. The ruling's own escape clause sent it back, and ruling #2 selected B:

Ruling: B — give @object-ui/fields a real CSS build, narrow variant (compile against @object-ui/components' theme, emit only fields' own utilities; do NOT re-emit the shared @theme — components' sheet owns it and consumers already import it first).

What was broken

packages/fields/package.json declared "./style.css": "./dist/index.css" while scripts.build was tsc && vite build and the package contained no .css file for Vite to extract. The published @object-ui/fields@17.3.0 tarball contains zero .css files. The subpath did not render badly — it failed to resolve, taking the consumer's build down.

Nothing in this repo noticed, structurally: apps/console, examples/console-starter and examples/byo-backend-console all reach fields' source through @source '.../packages/fields/src/**', a workspace-relative path no published consumer can write. In-repo rendering never exercised the export.

Implementation

packages/fields/src/index.css — a build-time-only Tailwind entry:

@reference '../../components/src/index.css';
@import 'tailwindcss/utilities.css' layer(utilities) source(none);
@source './**/*.{ts,tsx}';
@source not './**/*.test.{ts,tsx}';

@reference makes components' theme tokens, its class-based dark variant and its animate plugin available for resolution while emitting nothing of them — no preflight, no @theme :root block, no base layer.

packages/fields/scripts/build-css.mjs — mirrors packages/components/scripts/build-css.mjs, then subtracts every rule components' built sheet already ships.

How the coupling to components' unpublished source is expressed

Two build-time relative paths inside the monorepo, neither reachable from the published tarball:

what	where	why
theme / variants / plugin	@reference '../../components/src/index.css'	resolution only; emits nothing
the set to subtract	reads packages/components/dist/index.css	that package's real build output = "what the consumer already has"

This mirrors components' own build script's coupling to its src/index.css, one directory further away. turbo run build orders it correctly via dependsOn: ["^build"]; a bare single-package build fails with an actionable message naming pnpm --filter @object-ui/components build.

Reading components' built artifact rather than re-compiling its entry is deliberate — see "two bugs found" below.

Result

✓ built dist/index.css (21.57 kB) — 161 rules kept (157 classes),
  1351 rules + 75 at-rules already in @object-ui/components' sheet

21.57 kB instead of ~180 kB. The naive entry re-emits preflight, the theme and ~1350 utilities the consumer already has — the same objection that retired two @source lines in #3884 for costing 100 kB and buying 14 selectors.

Acceptance evidence

Re-ran the issue's subset comparator against the built artifact:

measured fields-only classes (the 152): 152
NOT covered by the final dist/index.css : 0  []
final sheet classes: 157 | overlap with components published: [ 'dark', 'group' ]

All 152 covered, zero uncovered. The only two overlapping names are variant markers appearing inside compound selectors (.dark\:x:where(.dark, .dark *), .group-hover\:y:is(:where(.group):hover *)), not duplicated utility rules — so duplication is effectively nil. The delta of 157 vs 152 is 5 classes present in fields' source but tree-shaken out of the dist bundle the original measurement scanned, plus those 2 markers; a superset in the safe direction.

All 17 theme-token utilities that only this build can produce are present: bg-background/60, bg-destructive/5, bg-muted/60, bg-primary/20, border-background, border-border/40, border-muted-foreground/25, border-muted-foreground/30, focus-visible:ring-ring/60, focus:ring-ring/60, hover:bg-accent/30, hover:bg-muted/80, hover:bg-primary/10, hover:bg-primary/50, hover:border-primary/50, ring-border/60, ring-destructive/50.

The export now resolves for real — npm pack --dry-run:

css files: [ "dist/index.css (22091B)", "src/index.css (1472B)" ]
total entries: 302

(src/index.css ships because files lists src, but exports has no subpath reaching it, so it stays encapsulated. Its header says build-time-only.)

Two bugs found and fixed while building this

Both would have shipped a wrong stylesheet with a green build, so they are worth naming:

1. Re-compiling components' entry was cwd-dependent. Tailwind's automatic source detection resolves against the process cwd, so compiling components' entry from fields' directory scanned packages/fields and folded fields' own classes into the set being subtracted. Every fields-only rule then looked "already shipped". Fixed by reading components' built dist/index.css instead — an artifact, not a re-derivation.
2. The same cwd sensitivity on fields' own entry. Run from the package it produced 21 kB; run from the repo root, 287 kB / 1923 classes of other packages' utilities. Fixed with source(none), which pins the inputs to the explicit @source lines. Verified byte-identical from both working directories.

The build now refuses to write on four conditions: a rule went missing, nothing was subtracted, a named theme-token sentinel vanished, or the class count exceeds a generous leak-detector ceiling.

The durable gate

Extends scripts/__tests__/package-files-exist.test.ts — the existing home for manifest discipline (objectui#3663 / #3696) — with an exports-reality section asking two questions:

1. Packability — is the target inside something files ships? (@object-ui/app-shell is the live positive case: it lists src/styles.css in files precisely so its subpath resolves.)
2. Producibility, for stylesheets — a .css target no committed file supplies must have a producer: a CSS source under src/, or a CSS step in the build script. Both derived from the package's own plumbing, never a name allowlist.

The objectui#3663 guard could not catch this: dist/index.css is git-ignored, untracked, and the package has a build script, so it was excused as build output — that guard says of itself "What this guard deliberately does NOT prove: that a build output is really produced." This closes exactly that gap for the one file type where the question is decidable statically. .js/.d.ts targets deliberately get no producibility test; there is no honest static answer for them and the gap is named rather than guessed at.

Producibility keys on git's index, not on onDisk. That was a correction the reverse verification forced: the first version passed against a tree where dist/index.css was sitting there from a local build — green on the very state it exists to reject.

Reverse verification

Predicted direction: red on the pre-fix state, in both build states (the second is the one the onDisk version got wrong).

state	result
pre-fix, dist/index.css absent	3 failed / 15 passed
pre-fix, stale dist/index.css present	3 failed / 15 passed
post-fix, dist/index.css present	18 passed
post-fix, dist/index.css absent	18 passed

The failure message is the defect verbatim:

@object-ui/fields exports "./style.css" -> "./dist/index.css", but the package has no CSS
source under src/ and its build script does not run a CSS step (build: "tsc && vite build")

Taken out with git checkout origin/main -- PATH and file moves — never git stash.

Docs

Re-teaches the fields import on the three pages PR #4060 removed it from (quick-start Step 3, theming §Tailwind Setup, troubleshooting §2), each stating the import order and that the fields sheet is a supplement that styles nothing on its own.

quick-start.md:60's "you do not add @source lines for the ObjectUI packages" is kept but repaired: it was measured true for components and generalized across the package boundary, where it was false for fields. With this change it is true for both, which is what makes it keepable rather than deletable.

The troubleshooting parenthetical that told readers "its published package contains no stylesheet … Do not add it" is replaced with the version fact — releases through 17.3.0 shipped none, so on those versions the import still fails and the fix is to upgrade, not to add scanning paths.

Changeset

minor, argued from the never-worked fact: this is the first release in which the import resolves at all, so it is a new capability rather than a repaired one, and an import that never resolved can have no working consumers to break. Not major per AGENTS.md §202-206 (the fixed group must track @objectstack's major). Bump Policy check arbitrates.

Verification

check	result
pnpm --filter @object-ui/fields build	✅ exit 0, dist/index.css 21.57 kB
npx vitest run packages/fields --maxWorkers=2	✅ 74 files, 1173 tests
npx vitest run scripts/__tests__ --maxWorkers=2	✅ 27 files, 500 tests
pnpm --filter @object-ui/fields type-check	✅ exit 0
pnpm --filter @object-ui/fields lint	✅ 0 errors (746 pre-existing warnings)
pnpm type-check:scripts	✅ exit 0
check-lint-coverage / check-type-check-coverage	✅ 45/45 linted
check-changeset-presence / -no-major / -fixed	✅ all exit 0
check-control-bytes + targeted self-scan	✅ clean
check-doc-links	✅ valid across 7 scan roots

Scope

Region exclusivity vs the in-flight #3569 branch respected: no GridField* or other source component file touched. The packages/fields surface is its package.json, a new src/index.css and a new scripts/build-css.mjs — the CSS entry the ruling explicitly put in scope.

---

Generated by Claude Code

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 10, 2026 4:35am

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	28.3 KB	350 KB
Entry file	index-B_dZfRii.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	8.66KB	3.13KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	7.57KB	2.97KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	22.10KB	4.37KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	35.76KB	9.11KB
auth (createAuthenticatedFetch.js)	4.37KB	1.69KB
auth (index.js)	2.35KB	1.07KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.91KB	0.87KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	483.91KB	106.75KB
core (index.js)	3.04KB	1.15KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	139.61KB	35.99KB
fields (index.js)	228.51KB	56.69KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	2.65KB	1.06KB
i18n (pickLocalized.js)	1.70KB	0.83KB
i18n (provider.js)	9.48KB	3.27KB
i18n (useObjectLabel.js)	27.59KB	6.63KB
i18n (useSafeTranslation.js)	4.52KB	1.96KB
layout (index.js)	38.84KB	10.80KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	8.75KB	3.06KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.67KB	1.12KB
permissions (evaluator.js)	4.41KB	1.44KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.55KB	0.71KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	45.23KB	12.45KB
plugin-charts (index.js)	61.49KB	17.48KB
plugin-chatbot (index.js)	180.33KB	42.79KB
plugin-dashboard (index.js)	118.50KB	30.66KB
plugin-designer (index.js)	210.51KB	42.51KB
plugin-detail (index.js)	237.80KB	59.48KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	113.81KB	27.53KB
plugin-gantt (index.js)	162.79KB	39.67KB
plugin-grid (index.js)	187.97KB	49.79KB
plugin-kanban (index.js)	48.53KB	13.38KB
plugin-list (index.js)	109.96KB	26.64KB
plugin-map (index.js)	17.00KB	5.32KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	40.58KB	10.58KB
plugin-timeline (index.js)	26.21KB	7.52KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.03KB	20.55KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.67KB	2.37KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	23.71KB	7.95KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.23KB	0.66KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	4.47KB	2.03KB
sdui-parser (parse.js)	10.04KB	2.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	4.69KB	1.48KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	2.71KB	1.34KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped