Skip to content

Commit cb82ec8

Browse files
xuyushun441-sysos-zhuangclaude
authored
docs(skill,showcase): SDUI styling (ADR-0065) — skill section + renderable showcase page (#2221)
- objectstack-ui skill: new 'Styling (ADR-0065)' section (responsiveStyles + design tokens, NOT className; properties.children; responsive via breakpoint maps not md:; worked example) + generic styleable blocks (flex/element:text/ element:button) added to the Component Catalogue. This is the AI-author contract — the skill previously had zero styling guidance. - app-showcase: new renderable page styling-gallery.page.ts (definePage, type 'app') styled entirely via responsiveStyles + tokens, wired into nav + objectstack.config. Typechecks clean against the merged spec; browser-verified end-to-end through the real renderer (89 scoped <style> tags, $29 -> 40px). Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 0976408 commit cb82ec8

5 files changed

Lines changed: 200 additions & 2 deletions

File tree

examples/app-showcase/objectstack.config.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ import { ChartGalleryDashboard, OpsDashboard } from './src/dashboards/index.js';
2222
import { ShowcaseTaskDataset, ShowcaseProjectDataset } from './src/datasets/index.js';
2323
import { allReports } from './src/reports/index.js';
2424
import { allActions } from './src/actions/index.js';
25-
import { ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage } from './src/pages/index.js';
25+
import { ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage, StylingGalleryPage } from './src/pages/index.js';
2626
import { allFlows } from './src/flows/index.js';
2727
import { allWebhooks } from './src/webhooks/index.js';
2828
import { allHooks } from './src/hooks/index.js';
@@ -156,7 +156,7 @@ export default defineStack({
156156
apps: [ShowcaseApp],
157157
portals: allPortals,
158158
views: [TaskViews, ProjectViews, InquiryViews, BusinessUnitViews],
159-
pages: [ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage],
159+
pages: [ComponentGalleryPage, ProjectWorkspacePage, ProjectDetailPage, TaskWorkbenchPage, TaskTriagePage, TaskBoardPage, TaskCalendarPage, TaskGalleryPage, TaskSchedulePage, TaskTimelinePage, TaskMapPage, TaskAllViewsPage, ActiveProjectsPage, TaskDetailPage, AccountDetailPage, ReviewQueuePage, NewProjectWizardPage, MyWorkPage, SettingsPage, StylingGalleryPage],
160160
dashboards: [ChartGalleryDashboard, OpsDashboard],
161161
books: allBooks,
162162
datasets: [ShowcaseTaskDataset, ShowcaseProjectDataset],

examples/app-showcase/src/apps/index.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ export const ShowcaseApp = App.create({
6464
icon: 'layout',
6565
children: [
6666
{ id: 'nav_gallery', type: 'page', pageName: 'showcase_component_gallery', label: 'Component Gallery', icon: 'layout-template' },
67+
{ id: 'nav_styling_gallery', type: 'page', pageName: 'showcase_styling_gallery', label: 'Styling (ADR-0065)', icon: 'palette' },
6768
{ id: 'nav_project_workspace', type: 'page', pageName: 'showcase_project_workspace', label: 'New Project + Tasks', icon: 'folder-plus' },
6869
// ADR-0047 interface mode: same object as nav_tasks, curated surface.
6970
{ id: 'nav_task_workbench', type: 'page', pageName: 'showcase_task_workbench', label: 'Task Workbench', icon: 'sliders-horizontal' },

examples/app-showcase/src/pages/index.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ export { ReviewQueuePage } from './review-queue.page.js';
1313
export { NewProjectWizardPage } from './new-project-wizard.page.js';
1414
export { MyWorkPage } from './my-work.page.js';
1515
export { SettingsPage } from './settings.page.js';
16+
export { StylingGalleryPage } from './styling-gallery.page.js';
1617
export {
1718
TaskBoardPage,
1819
TaskCalendarPage,
Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { definePage } from '@objectstack/spec/ui';
4+
5+
/**
6+
* Styling Gallery (ADR-0065) — the canonical example of the SDUI scoped-styling
7+
* model. A pricing page composed from generic blocks (`flex` / `element:text` /
8+
* `element:button`) that each carry a `responsiveStyles` object (per-breakpoint
9+
* CSS-property maps) with **design-token values** (`var(--space-*)`,
10+
* `var(--surface)`, `var(--brand)`, `hsl(var(--primary))`, …) — NO `className`.
11+
*
12+
* objectui's `SchemaRenderer` compiles each node's `responsiveStyles` to
13+
* **id-scoped CSS** injected as an unlayered `<style>` at render: build-independent
14+
* (arbitrary values + tokens pass through verbatim), collision-free (per-node
15+
* scope beats base utilities without `@layer` games), responsive-correct
16+
* (breakpoint maps → generated `@media`, never `md:` classes). This is the
17+
* preferred way to style a metadata-authored page; see the objectstack-ui skill
18+
* "Styling (ADR-0065)" section.
19+
*
20+
* Note: child nodes go in `properties.children` (the renderer hoists `properties`
21+
* to schema level at render); `responsiveStyles`/`id` are top-level envelope fields.
22+
*/
23+
24+
/** One checklist line: an accent-coloured check + the label. */
25+
function feature(label: string): any {
26+
return {
27+
id: `feat_${label}`,
28+
type: 'flex',
29+
responsiveStyles: { large: { display: 'flex', alignItems: 'flex-start', gap: 'var(--space-2)' } },
30+
properties: {
31+
children: [
32+
{ id: `feat_${label}_chk`, type: 'element:text', responsiveStyles: { large: { color: 'hsl(var(--primary))', fontWeight: '700', lineHeight: '1.5' } }, properties: { content: '✓' } },
33+
{ id: `feat_${label}_lbl`, type: 'element:text', responsiveStyles: { large: { fontSize: '14px', color: 'var(--text-strong)', lineHeight: '1.5' } }, properties: { content: label } },
34+
],
35+
},
36+
};
37+
}
38+
39+
/** A plan column — a styled `flex` box (no opinionated page:card). */
40+
function planCard(o: { name: string; price: string; period: string; tagline: string; features: string[]; cta: string; popular?: boolean }): any {
41+
return {
42+
id: `plan_${o.name}`,
43+
type: 'flex',
44+
responsiveStyles: {
45+
large: {
46+
display: 'flex', flexDirection: 'column', gap: 'var(--space-4)',
47+
padding: 'var(--space-6)', borderRadius: 'var(--radius-xl)',
48+
backgroundColor: 'var(--surface)',
49+
border: o.popular ? '1px solid hsl(var(--primary))' : '1px solid var(--hairline)',
50+
boxShadow: o.popular ? '0 0 0 3px hsl(var(--primary) / 0.25), var(--shadow-lg)' : 'var(--shadow-sm)',
51+
},
52+
small: { padding: 'var(--space-4)', gap: 'var(--space-3)' },
53+
},
54+
properties: {
55+
children: [
56+
...(o.popular
57+
? [{ id: `plan_${o.name}_badge`, type: 'element:text', responsiveStyles: { large: { alignSelf: 'flex-start', fontSize: '12px', fontWeight: '600', color: 'var(--brand-foreground)', backgroundColor: 'var(--brand)', padding: '2px 10px', borderRadius: '999px' } }, properties: { content: 'Most popular' } }]
58+
: []),
59+
{ id: `plan_${o.name}_name`, type: 'element:text', responsiveStyles: { large: { fontSize: '13px', fontWeight: '600', color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.06em' } }, properties: { content: o.name } },
60+
{
61+
id: `plan_${o.name}_price_row`, type: 'flex',
62+
responsiveStyles: { large: { display: 'flex', alignItems: 'baseline', gap: 'var(--space-2)' } },
63+
properties: {
64+
children: [
65+
{ id: `plan_${o.name}_price`, type: 'element:text', responsiveStyles: { large: { fontSize: '40px', fontWeight: '700', color: 'var(--text-strong)', fontVariantNumeric: 'tabular-nums' }, small: { fontSize: '32px' } }, properties: { content: o.price } },
66+
{ id: `plan_${o.name}_period`, type: 'element:text', responsiveStyles: { large: { fontSize: '13px', color: 'var(--text-muted)' } }, properties: { content: o.period } },
67+
],
68+
},
69+
},
70+
{ id: `plan_${o.name}_tagline`, type: 'element:text', responsiveStyles: { large: { fontSize: '13px', color: 'var(--text-muted)', minHeight: '34px' } }, properties: { content: o.tagline } },
71+
{ id: `plan_${o.name}_divider`, type: 'flex', responsiveStyles: { large: { height: '1px', backgroundColor: 'var(--hairline)', margin: 'var(--space-1) 0' } }, properties: { children: [] } },
72+
...o.features.map(feature),
73+
{ id: `cta_${o.name}`, type: 'element:button', responsiveStyles: { large: { marginTop: 'auto', width: '100%' } }, properties: { label: o.cta, variant: o.popular ? 'primary' : 'secondary', size: 'large' } },
74+
],
75+
},
76+
};
77+
}
78+
79+
export const StylingGalleryPage = definePage({
80+
name: 'showcase_styling_gallery',
81+
label: 'Styling (ADR-0065)',
82+
type: 'app',
83+
template: 'default',
84+
kind: 'full',
85+
isDefault: false,
86+
regions: [
87+
{
88+
name: 'main',
89+
width: 'full',
90+
components: [
91+
{
92+
id: 'styling_root',
93+
type: 'flex',
94+
responsiveStyles: {
95+
large: { minHeight: '100%', display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--space-8)', padding: 'var(--space-12) var(--space-6)' },
96+
small: { padding: 'var(--space-8) var(--space-4)' },
97+
},
98+
properties: {
99+
children: [
100+
{
101+
id: 'styling_header', type: 'flex',
102+
responsiveStyles: { large: { display: 'flex', flexDirection: 'column', gap: 'var(--space-3)', textAlign: 'center', maxWidth: '42rem' } },
103+
properties: {
104+
children: [
105+
{ id: 'styling_title', type: 'element:text', responsiveStyles: { large: { fontSize: '40px', fontWeight: '700', letterSpacing: '-0.02em', color: 'var(--text-strong)' }, small: { fontSize: '30px' } }, properties: { content: 'Plans & Pricing' } },
106+
{ id: 'styling_subtitle', type: 'element:text', responsiveStyles: { large: { fontSize: '16px', color: 'var(--text-muted)' } }, properties: { content: 'Styled entirely with responsiveStyles + design tokens — zero Tailwind class strings (ADR-0065).' } },
107+
],
108+
},
109+
},
110+
{
111+
id: 'plan_grid', type: 'flex',
112+
responsiveStyles: {
113+
large: { display: 'grid', gridTemplateColumns: 'repeat(4, minmax(0,1fr))', gap: 'var(--space-6)', width: '100%', maxWidth: '80rem', alignItems: 'stretch', marginTop: 'var(--space-4)' },
114+
medium: { gridTemplateColumns: 'repeat(2, minmax(0,1fr))' },
115+
small: { gridTemplateColumns: '1fr' },
116+
},
117+
properties: {
118+
children: [
119+
planCard({ name: 'Free', price: '$0', period: 'forever', tagline: 'For evaluating and small personal projects.', features: ['1 environment', '3 users', 'AI online development', '7-day audit retention'], cta: 'Get started' }),
120+
planCard({ name: 'Solo', price: '$29', period: 'per month', tagline: 'For solo builders and indie makers.', features: ['2 environments', '10 users', 'Custom domains', 'Stronger AI model', '30-day audit retention'], cta: 'Upgrade to Solo', popular: true }),
121+
planCard({ name: 'Team', price: '$99', period: 'per month', tagline: 'For teams shipping real apps.', features: ['2 environments', '100 users', 'Custom domains', '30-day audit retention'], cta: 'Upgrade to Team' }),
122+
planCard({ name: 'Business', price: '$299', period: 'per month', tagline: 'For organizations that need SSO and scale.', features: ['4 environments', '500 users', 'SSO / SAML', '1-year audit retention'], cta: 'Upgrade to Business' }),
123+
],
124+
},
125+
},
126+
],
127+
},
128+
},
129+
],
130+
},
131+
],
132+
});

skills/objectstack-ui/SKILL.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -562,6 +562,9 @@ which contain components.
562562
|:---------------------|:----|
563563
| `page:header` | Title + subtitle + breadcrumb + inline `actions: Action[]` |
564564
| `page:card` | Bordered/un-bordered card with `body: Component[]` |
565+
| `flex` | Generic styleable box (`properties.children`) — the workhorse for custom layout; style via `responsiveStyles` (see Styling below) |
566+
| `element:text` | Text node — `properties.content`; style via `responsiveStyles` |
567+
| `element:button` | Button — `properties.label` + `variant`/`size` + optional `action` |
565568
| `record:highlights` | Salesforce highlights panel — strip of key fields |
566569
| `record:path` | Stage progress bar driven by a status field |
567570
| `record:related` | Related-list (child records via lookup) |
@@ -630,6 +633,67 @@ export const LeadDetailPage = definePage({
630633
> `page:header.properties.actions`; do **not** create a sibling action node.
631634
> The header renders them inline in the action slot.
632635
636+
### Styling a page (ADR-0065) — `responsiveStyles`, NOT `className`
637+
638+
To style a metadata-authored block, give it a **`responsiveStyles`** object — a
639+
per-breakpoint map of CSS properties. The renderer compiles each styled node to
640+
**id-scoped CSS** at render time. **Do NOT put Tailwind classes in `className`**
641+
expecting them to render: Tailwind is compiled at the *renderer's* build over the
642+
*renderer's* source, never over your metadata, so a class only happens to work if
643+
objectui already uses it — arbitrary classes (`text-[27px]`, `bg-[#1a2b3c]`,
644+
`grid-cols-7`) silently do nothing. `responsiveStyles` has no such trap (values
645+
are compiled from your data at render).
646+
647+
Rules:
648+
- **`responsiveStyles` and `id` are top-level** envelope fields; **child nodes go
649+
in `properties.children`** (the renderer hoists `properties` to schema level).
650+
- Every styled node **needs a stable `id`** (the CSS is scoped to it).
651+
- **Values should be design tokens** for consistency: spacing `var(--space-1..12)`,
652+
radius `var(--radius)` / `var(--radius-xl)`, shadow `var(--shadow-sm|md|lg)`,
653+
colors `var(--surface)` / `var(--surface-sunken)` / `var(--text-strong)` /
654+
`var(--text-muted)` / `var(--brand)` / `var(--brand-foreground)` /
655+
`var(--hairline)`, or `hsl(var(--primary))` etc. (theme tokens track light/dark).
656+
- **Responsive lives in the breakpoint maps**`large` (base, desktop-first),
657+
then `medium` / `small` / `xsmall` as `max-width` overrides. **Never** author
658+
`md:`-style variant classes.
659+
- **Compose from generic styleable blocks**`flex`, `element:text`,
660+
`element:button` — and style each block's root. (`page:card` etc. are fine for
661+
structure but style what you control.)
662+
663+
```typescript
664+
// A styled pricing card — every block carries responsiveStyles + tokens.
665+
{
666+
id: 'plan_solo', type: 'flex',
667+
responsiveStyles: {
668+
large: {
669+
display: 'flex', flexDirection: 'column', gap: 'var(--space-4)',
670+
padding: 'var(--space-6)', borderRadius: 'var(--radius-xl)',
671+
backgroundColor: 'var(--surface)', border: '1px solid hsl(var(--primary))',
672+
boxShadow: '0 0 0 3px hsl(var(--primary) / 0.25), var(--shadow-lg)',
673+
},
674+
small: { padding: 'var(--space-4)', gap: 'var(--space-3)' }, // responsive via the model
675+
},
676+
properties: {
677+
children: [
678+
{ id: 'plan_solo_price', type: 'element:text',
679+
responsiveStyles: { large: { fontSize: '40px', fontWeight: '700', color: 'var(--text-strong)' }, small: { fontSize: '32px' } },
680+
properties: { content: '$29' } },
681+
{ id: 'cta_solo', type: 'element:button',
682+
responsiveStyles: { large: { marginTop: 'auto', width: '100%' } }, // pin CTA to card bottom
683+
properties: { label: 'Upgrade', variant: 'primary', size: 'large' } },
684+
],
685+
},
686+
}
687+
```
688+
689+
Why this model: it's **build-independent** (no Tailwind compile dependency),
690+
**collision-free** (per-node scoped, beats base utilities without `@layer`
691+
games), and **responsive-correct** (breakpoint maps → generated `@media`). The
692+
spec field is `PageComponentSchema.responsiveStyles` (`@objectstack/spec`,
693+
`ResponsiveStylesSchema`). Full worked example:
694+
`examples/app-showcase/src/pages/styling-gallery.page.ts` (the "Styling
695+
(ADR-0065)" nav entry). See [ADR-0065](../../docs/adr/0065-sdui-styling-model.md).
696+
633697
---
634698

635699
## Docs — Package Documentation (ADR-0046)

0 commit comments

Comments
 (0)