docs(plugin-kanban): document the badge element's colorClass / colorStyle members

[baozhoutao]

Fixes #7984

packages/plugin-kanban/README.md's KanbanCard block documented the badges element with 2 of the 4 members carried by the shipped declaration. This adds colorClass and colorStyle in the shipped order, with one comment line naming the pairing rule. Source of truth: packages/types/src/complex.ts (KanbanCard at :63), which @object-ui/plugin-kanban re-exports through src/types.ts:36. No packages/** source is touched — the diff is 2 added lines in one README.

Side-by-side — the review IS the verification

No gate reds on this (see Why no gate holds it below), so please compare these by eye.

Shipped, packages/types/src/complex.ts:67-89 — JSDoc bodies elided to the load-bearing sentences; the full text is in the file:

  badges?: Array<{
    label: string;
    variant?: "default" | "secondary" | "destructive" | "outline";
    /**
     * Optional Tailwind class string applied to the badge. When set, it
     * overrides `variant` ...
     * Derive it the way the grid cell derives it, or the same option renders
     * two colours on one screen (objectui#5183): prefer
     * `getBadgeHexAppearance(color)` from `@object-ui/fields` and use its
     * `className` — passing its `colorStyle` too — and fall back to
     * `getBadgeColorClasses(color, value)` only when it returns `undefined`.
     */
    colorClass?: string;
    /**
     * Inline style accompanying `colorClass`. **Required whenever the class
     * string came from `getBadgeHexAppearance`** — that className reads CSS
     * custom properties which only this style declares, so a badge carrying
     * the class without the style references undefined variables. ...
     */
    colorStyle?: React.CSSProperties;
  }>;

README after this change, packages/plugin-kanban/README.md:129-135:

  badges?: Array<{
    label: string;
    variant?: 'default' | 'secondary' | 'destructive' | 'outline';
    colorClass?: string;
    colorStyle?: React.CSSProperties; // Required whenever colorClass came from getBadgeHexAppearance(color) in @object-ui/fields — the class reads CSS custom properties only this style declares (objectui#5183)
  }>;

Four member names, in the shipped order, with the shipped types (the README block's own single-quote convention for the variant union is kept, as is its // … trailing-comment style). The whole JSDoc is deliberately not transcribed — one line carries the pairing rule, which is the half a README reader cannot otherwise discover.

The pairing rule, in one line

A colorClass derived from getBadgeHexAppearance(color) (from @object-ui/fields) must be passed together with that helper's style as colorStyle, because the class reads CSS custom properties that only that style declares. A badge carrying the class without the style references undefined variables; deriving the class some other way is how one option renders two colours on one screen (objectui#5183).

Why no gate holds it (and why no gate was edited here)

Both boundaries are declared in the gates' own headers, so neither is a bug to patch:

• scripts/check-readme-exports.mjs compares top-level property names only, in both directions, and its :576 header says nested declarations are deliberately not walked. A nested member is outside the pin by design.
• packages/plugin-kanban/README.md is on scripts/check-doc-snippet-types.mjs's UNGATED_DOCS ledger at :728 (6 parse diagnostic(s) — blocks fenced ts that are bare object literals or elided bodies), so its fences are never compiled. That ledger is objectui#5174's shrink-only debt list and shrinking it has its own route.

Per the triage ruling on the card (§3), widening either gate is a separate card; this PR edits neither.

Reader named in the dispatch, measured after the change — node scripts/check-readme-exports.mjs --list, run on this branch's HEAD 6316cfd8:

matches            packages/plugin-kanban/README.md:125  interface KanbanCard  doc 7 key(s) + 0 method(s) vs own 7 of 7
matches            packages/plugin-kanban/README.md:114  interface KanbanColumn  doc 7 key(s) + 0 method(s) vs own 7 of 7

Still 7 vs 7, as predicted: the addition is nested, so the top-level pin sees nothing move.

Control that the page is still ungated — pnpm check:doc-snippets exit 0, and its census line still reads 227 document(s): 214 covered ..., 13 ungated — declared in this script, NOT verified by it, with this README among the 13. So React.CSSProperties in the block needs no import type today; nothing compiles it. It is written with the React. namespace spelling the shipped declaration uses, so it will still compile if and when this page comes off the ledger.

Scope notes

• objectui#6155 is open and records four disagreeing declarations of the KanbanCard / KanbanColumn pair. If whoever reconciles those moves this element, the README is re-touched once — one code block, a cheap second pass, and much cheaper than leaving a shipped README two members short indefinitely. That card is pm:blocked, and per triage this one is not mechanically blocked by it.
• objectui#5174 batch 26 is a likely pick for this README. This lands first; batch 26 re-reads the block.
• objectui#7742 (KanbanSchema's zero-read members and the root README's kanban example) is the same family on a different face and is not part of this PR.
• Last writer on this file was PR docs(plugins): bring three documented interface blocks up to their shipped types #7985 (objectui#7302), landed. Verified at branch-cut: no active branch touches this path — the four copilot/* kanban branches that differ on it last moved 2026-01-14 through 2026-02-04 and sit 200–1977 commits behind main, and claude/issue-5174-ungated-docs-batch25 does not touch it.

Gates

All run in this worktree at HEAD 6316cfd8, exit codes captured by redirect-then-capture:

Gate	Exit	Verdict line
pnpm check:readme-exports	0	✅ check-readme-exports: OK (... 58 key(s) compared both ways (0 fabricated, 0 stale omission(s) ...))
pnpm exec vitest run scripts/__tests__/check-readme-exports.test.ts	0	Test Files 1 passed (1) · Tests 87 passed (87)
pnpm check:doc-fences	0	✅ check:doc-fences — every TypeScript block in 227 document(s) is fenced ts/tsx/typescript ...
pnpm check:doc-types	0	✅ Every documented component type is registered.
node scripts/check-doc-links.mjs	0	Links are valid across 17 scan roots.
pnpm check:doc-snippets (control)	0	Semantic phase: 567 of 567 block(s) judged, 0 failed. — this page among the 13 ungated
pnpm check:control-bytes	0	✅ check-control-bytes: OK (scanned 6502 tracked text file(s); skipped 85 binary).
node scripts/check-changeset-presence.mjs	0	✅ No source or published contract of a released package changed in this range, so no changeset is owed.
node scripts/check-governed-queue-guard.mjs --test packages/plugin-kanban/README.md	0	✅ NOT GOVERNED — 1 path(s) checked against 5 governed surface(s); none matched.

Plus a self-scan of the changed path for control bytes: grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' packages/plugin-kanban/README.md exit 1 (no hits).

Changeset: none added. check-changeset-presence.mjs is the authority and it reads 1 file(s) changed, 0 of them published source of a package the release covers — a README is not published source to that script, so nothing is owed. No skip-changeset label was applied.

Live E2E (informational) is red on every branch today for an upstream reason (objectui#7990 / objectstack#16186) — not from this change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

---

Generated by Claude Code

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Eager closure (gzip, 50 chunks)	3186.6 KB	3191.4 KB
Main entry chunk (gzip)	143.6 KB	350 KB
Entry file	index-Cs9mOUgK.js	—
Status	PASS	—

The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it.

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (consoleActionDispatch.js)	0.20KB	0.19KB
app-shell (index.js)	15.67KB	5.75KB
app-shell (runtime-config.js)	20.68KB	7.36KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	10.06KB	3.86KB
auth (ActiveOrganizationStorage.js)	25.05KB	9.16KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	2.07KB	1.00KB
auth (AuthProvider.js)	40.18KB	10.59KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.15KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.65KB	2.22KB
auth (SocialSignInButtons.js)	9.61KB	3.89KB
auth (UserMenu.js)	3.41KB	1.23KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	40.21KB	10.80KB
auth (createAuthenticatedFetch.js)	8.46KB	3.43KB
auth (index.js)	3.19KB	1.44KB
auth (invitation-status.js)	1.22KB	0.70KB
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)	5.30KB	1.02KB
auth (useWorkspaceAdminStatus.js)	5.13KB	2.35KB
collaboration (CommentThread.js)	26.08KB	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.68KB	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)	498.06KB	113.97KB
core (index.js)	6.96KB	2.79KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	182.08KB	50.62KB
fields (index.js)	242.43KB	61.25KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (builtinAggregateLabels.js)	0.86KB	0.49KB
i18n (currency.js)	1.22KB	0.64KB
i18n (fallbackInterpolation.js)	6.25KB	2.77KB
i18n (i18n.js)	6.57KB	2.76KB
i18n (index.js)	3.65KB	1.47KB
i18n (pickLocalized.js)	7.62KB	3.26KB
i18n (provider.js)	26.89KB	9.04KB
i18n (useDisplayLocale.js)	2.85KB	1.45KB
i18n (useObjectLabel.js)	34.34KB	9.17KB
i18n (useSafeTranslation.js)	5.60KB	2.33KB
layout (index.js)	38.84KB	10.94KB
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.75KB
mobile (index.js)	1.99KB	0.87KB
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.72KB	0.42KB
mobile (useSpecGesture.js)	4.39KB	1.66KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	11.71KB	4.29KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	6.24KB	2.16KB
permissions (discardProofCache.js)	1.04KB	0.55KB
permissions (evaluator.js)	5.12KB	1.74KB
permissions (index.js)	0.93KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.53KB
permissions (usePermissions.js)	4.83KB	2.27KB
plugin-ai (index.js)	15.16KB	3.68KB
plugin-calendar (index.js)	47.29KB	13.18KB
plugin-charts (index.js)	70.35KB	19.68KB
plugin-chatbot (index.js)	193.54KB	46.04KB
plugin-dashboard (index.js)	131.41KB	34.43KB
plugin-designer (index.js)	211.51KB	43.01KB
plugin-detail (index.js)	247.75KB	63.50KB
plugin-editor (index.js)	2.23KB	1.05KB
plugin-form (index.js)	131.01KB	32.32KB
plugin-gantt (index.js)	167.16KB	40.99KB
plugin-grid (index.js)	208.58KB	56.63KB
plugin-kanban (index.js)	52.46KB	14.57KB
plugin-list (index.js)	113.34KB	27.72KB
plugin-map (index.js)	20.49KB	6.83KB
plugin-markdown (index.js)	13.88KB	4.80KB
plugin-report (index.js)	43.42KB	11.92KB
plugin-timeline (index.js)	30.10KB	8.74KB
plugin-tree (index.js)	9.33KB	3.25KB
plugin-view (index.js)	84.48KB	20.81KB
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.66KB	3.50KB
providers (index.js)	0.45KB	0.23KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.62KB	2.34KB
react (LazyPluginLoader.js)	4.47KB	1.63KB
react (SchemaRenderer.js)	81.07KB	26.86KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	4.63KB	2.18KB
react (schema-input.js)	2.32KB	1.24KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	6.58KB	2.74KB
sdui-parser (dashboard-widget-options.js)	3.08KB	1.30KB
sdui-parser (index.js)	5.55KB	2.45KB
sdui-parser (input-type.js)	2.84KB	1.40KB
sdui-parser (parse.js)	20.57KB	5.88KB
sdui-parser (provenance.js)	3.66KB	1.82KB
sdui-parser (types.js)	0.28KB	0.23KB
sdui-parser (validate.js)	13.64KB	4.59KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	1.00KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	2.74KB	1.41KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (data-display.js)	3.75KB	1.85KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.85KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (expression.js)	0.20KB	0.18KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-inflight.js)	8.87KB	3.73KB
types (http-retry.js)	4.32KB	2.02KB
types (icon-key-migration.js)	4.26KB	1.63KB
types (index.js)	4.74KB	2.25KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	4.73KB	2.28KB
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 (select-option.js)	0.20KB	0.19KB
types (spec-report.js)	5.05KB	1.93KB
types (spec-ui-namespace.js)	0.20KB	0.19KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	6.28KB	2.87KB
types (ui-action.js)	8.11KB	3.32KB
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

[baozhoutao]

Standing down on Live E2E (informational) for this PR, read 2026-09-06T18:02Z.

• Failing check: Live E2E (informational) — informational, not a required context, and red on main and on every open branch today for an upstream reason tracked in ci(live-e2e): Live E2E (informational) is red on main and every branch since the backend pin moved to 17.2.0 — the published plugin-auth float (objectstack#16186), not an objectui diff #7990 / objectstack#16186. This diff is two lines inside a README fence that no gate compiles; nothing the live E2E exercises.
• Why it is not this PR's: base-red anchored on the two cards above; the failure names a service the diff does not touch.
• Fix ported: none exists yet in either repo; nothing to port.
• Re-run: not spent — a re-run of a base-red informational job cannot change the reading.

Every other check on 6316cfd82 is judged on its own; this PR flips to ready once the required set converges, then goes to the merge queue by squash.

---

Generated by Claude Code

[baozhoutao]

Armed — squash auto-merge enabled and the PR is in the merge queue, domain:devx @ objectui execution seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr, R46.

• Head 6316cfd82: 29 non-informational checks completed green at 18:04Z (the ci-wait reading); Live E2E (informational) per the standing-down note above.
• ready_for_review at 18:05:07Z; the post-flip Governed Surface Queue Guard run started after that timestamp and completed success at 18:05:23Z.
• added_to_merge_queue at 18:06:32Z on the REST timeline (read 18:06:42Z). PR ci: bound the six uncached jobs — four ceilings derived per job, two 360s accepted on the record #8129 is ahead of it in the queue.

On MERGED: content probe on re-fetched origin/main (colorClass?: string; and colorStyle?: React.CSSProperties; inside the badges element of packages/plugin-kanban/README.md; control: the variant?: line unchanged), then the LANDED note here and the closing stroke on #7984.

---

Generated by Claude Code

[baozhoutao]

LANDED — merged at 2026-09-06T18:21:43Z as 5533ae334 (squash, via the merge queue), domain:devx @ objectui execution seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr, R46.

Content probe on re-fetched origin/main (5533ae334, read 18:22:06Z), packages/plugin-kanban/README.md:

• colorClass?: string; at line 132 and colorStyle?: React.CSSProperties; with the pairing-rule comment at line 133, inside the badges element.
• Control: the variant?: 'default' | 'secondary' | 'destructive' | 'outline'; line is present once, unchanged.

#7984 closed by the Fixes at merge time; the seat strips pm:dispatched and clears the assignee there in the same stroke. objectui#5174 batch 26 (the kanban README pick) is now serialised only behind PR #8132 and objectui#7864.

---

Generated by Claude Code