From 5627996b0a173354d6c1a079148797a07dc766ee Mon Sep 17 00:00:00 2001 From: os-zhuang Date: Sun, 5 Jul 2026 01:29:08 +0800 Subject: [PATCH] docs(skills): teach adaptive record presentation in objectstack-ui skill (#2578) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a "Record Presentation — surface, width & columns are auto-derived" section to the objectstack-ui authoring skill. Nothing in the docs taught the deprecated primitives, but the new model (all metadata is AI-authored) was untaught: surface (page vs drawer), overlay width and column count are runtime-derived, so authors write fields + fieldGroups and never author presentation. Teaches span over colSpan, the size bucket over pixel width, and navigation.mode / a Page only as an override. Empty changeset (docs-only, no package release). Co-Authored-By: Claude Opus 4.8 --- .changeset/adaptive-ui-skill-doc.md | 4 ++++ skills/objectstack-ui/SKILL.md | 32 +++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 .changeset/adaptive-ui-skill-doc.md diff --git a/.changeset/adaptive-ui-skill-doc.md b/.changeset/adaptive-ui-skill-doc.md new file mode 100644 index 000000000..9cb0a50c4 --- /dev/null +++ b/.changeset/adaptive-ui-skill-doc.md @@ -0,0 +1,4 @@ +--- +--- + +docs(skills): teach adaptive record presentation (surface/width/columns auto-derived) in the objectstack-ui skill (#2578) diff --git a/skills/objectstack-ui/SKILL.md b/skills/objectstack-ui/SKILL.md index 97acc0152..4be8b6472 100644 --- a/skills/objectstack-ui/SKILL.md +++ b/skills/objectstack-ui/SKILL.md @@ -614,6 +614,38 @@ export const TaskWorkbenchPage = definePage({ --- +## Record Presentation — surface, width & columns are auto-derived + +A record's create / edit / detail **presents itself adaptively**. You do **not** +author the surface, the overlay width, or the column count — all three are derived +at runtime from how heavy the record is + the client viewport, because an author +(especially an AI) cannot know the client's screen. **Write the data (fields, +`fieldGroups`); let the platform lay it out.** + +- **Surface (page vs drawer).** Derived from field count: a field-heavy object + opens create/edit/detail as a **full page**; a light one as a **drawer**. Mobile + always pages. Don't set it. To force it for a specific object, set + `navigation.mode` (`page` | `drawer` | `modal`) on the list view (or object) — or, + for bespoke layout, assign a record `Page` (below). +- **Field width.** Use the relative **`span: 'full'`** to make a field take the + whole row; otherwise **omit it** (`auto` sizes by widget type × current columns — + textarea / rich-text / file take the row automatically). Do **not** use the + absolute `colSpan` — it only lines up at one width and is deprecated. +- **Overlay width.** Never author pixels. If you must nudge, use the **`size`** + bucket (`sm` | `md` | `lg` | `xl` | `full`) on `navigation`; the pixel + `width` / `drawerWidth` are deprecated (they can't be chosen without knowing the + client viewport). +- **Column count.** Not authored. The form grid follows its **real rendered width** + via container queries — the same form is 1 column in a narrow drawer and up to 4 + on a wide page. Author *grouping* with `fieldGroups` + `Field.group`; the columns + adapt themselves. + +> **Rule of thumb: presentation (surface / width / columns) is not metadata.** +> Write fields + semantic roles; the renderer decides the pixels. Reach for +> `navigation.mode` / `size` / a `Page` only to *override* — never as the default. + +--- + ## Pages — Lightning-Style Page Layouts A **Page** is a Salesforce-Lightning-style layout composed of **regions**