@loykin/designkit 0.0.3 → 0.0.5

package/docs/guides/managed-table.md

@@ -4,6 +4,8 @@ This is the normative implementation contract for a tabbed administrative table
 
 The Playground's **Guides / Resource Management / Managed Table** screen is the executable end-to-end reference. Its records are sample data; the pattern is defined by the table responsibilities and template composition below, not by that data domain. If an implementation differs from this contract, revise the implementation rather than inventing a local layout.
 
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) first.
+
 ## Pattern identity and reference registry
 
 - Pattern ID: `managed-table`
@@ -16,10 +18,10 @@ The Playground's **Guides / Resource Management / Managed Table** screen is the
 
 | Status               | Playground reference                           | Role in this pattern                                                                   |
 | -------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
-| Executable pattern   | `Guides / Resource Management / Managed Table` | Complete list, tabs, queries, create route, form, pagination, and concise detail Sheet |
+| Executable pattern   | `Guides / Resource Management / Managed Table` | Complete list, tabs, queries, create route, form, pagination, and concise detail SidePanel |
 | Supporting reference | `DataBodyTemplate / Table / Standard`          | Base GridKit table composition and table sizing                                        |
-| Supporting reference | `DataBodyTemplate / Form / Stacked`            | Create/edit form spacing, padding, and action alignment                                |
-| Supporting reference | `DetailBodyTemplate / Detail / Record`         | Full-page destination when detail outgrows a Sheet                                     |
+| Supporting contract  | `Guides / Forms / Stacked Form`                | Create/edit form spacing, modular Groups, and action alignment                         |
+| Supporting reference | `DetailBodyTemplate / Detail / Record`         | Full-page destination when detail outgrows a SidePanel                                     |
 | Supporting reference | `FormWizardBodyTemplate / Wizard`              | Multi-step destination when create/edit outgrows a stacked form                        |
 | Counterexample       | `DashboardBodyTemplate / Dashboard`            | Monitoring panels are not an administrative table                                      |
 | Counterexample       | `BrowseBodyTemplate / Browse`                  | Consumer discovery is not an administrative resource list                              |
@@ -32,8 +34,8 @@ Only the entry marked **Executable pattern** implements this pattern end to end.
 | -------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------- |
 | Collection list, tabs, search, filters, pagination | `DataBodyTemplate` + `DataBodyTemplate.Resource` | `Guides / Resource Management / Managed Table` |
 | Base table behavior                                | GridKit `DataGrid`                               | `DataBodyTemplate / Table / Standard`          |
-| Simple create/edit route                           | stacked `DataBodyTemplate.Group`                 | `DataBodyTemplate / Form / Stacked`            |
-| Concise read-only inspection                       | `Sheet`                                          | `Managed Table` row detail                     |
+| Simple create/edit route                           | stacked `DataBodyTemplate.Group`                 | `Guides / Forms / Stacked Form`                |
+| Concise read-only inspection                       | BaseKit `SidePanel` (`@loykin/side-panel`)       | `Managed Table` row detail                     |
 | Complex full-page detail route                     | `DetailBodyTemplate`                             | `DetailBodyTemplate / Detail / Record`         |
 | Multi-step create/edit route                       | `FormWizardBodyTemplate`                         | `FormWizardBodyTemplate / Wizard`              |
 | Destructive confirmation                           | `AlertDialog`                                    | UI primitive contract                          |
@@ -72,7 +74,7 @@ This guide covers three destinations for any managed resource:
 
 ```text
 /<resources>
-├─ select row    → concise read-only detail Sheet
+├─ select row    → concise read-only detail SidePanel
 ├─ create action → /<resources>/new create page
 └─ edit action   → /<resources>/:resourceId/edit page
 ```
@@ -84,12 +86,12 @@ It does not define every `DataBodyTemplate` use case. Settings, dashboards, long
 | User intent                                                                     | Default destination   | Reason                                                                  |
 | ------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------- |
 | Browse, search, filter, paginate                                                | Page                  | Stable, linkable working context                                        |
-| Inspect concise read-only row information                                       | Sheet                 | Preserves list context                                                  |
+| Inspect concise read-only row information                                       | SidePanel             | Preserves list context                                                  |
 | Create or edit an entity                                                        | Page with its own URL | Space for validation, permissions, responsive layout, and future fields |
-| Inspect long, editable, multi-section, permission-sensitive, or linkable detail | Page with its own URL | Sheet constraints are no longer appropriate                             |
+| Inspect long, editable, multi-section, permission-sensitive, or linkable detail | Page with its own URL | SidePanel constraints are no longer appropriate                        |
 | Confirm a destructive action or collect one narrowly scoped value               | Modal                 | Short, blocking decision                                                |
 
-A Sheet is not the default form container. Do not put general create or edit forms in a Sheet merely because the trigger originates in a table.
+A SidePanel is not the default form container. Do not put general create or edit forms in a SidePanel merely because the trigger originates in a table.
 
 ## Route and page hierarchy
 
@@ -156,7 +158,7 @@ Each tab must be a separate React component and own all state that affects its r
 - TanStack Query and query key
 - Search and filters
 - Pagination
-- Row selection and concise detail Sheet
+- Row selection and concise detail SidePanel
 - Mutations that belong to the list itself
 
 Query keys include every server-state input:
@@ -302,7 +304,7 @@ Grid rules:
 
 ## Create and edit form page
 
-Create and edit forms use the established Form / Stacked composition. Preserve the template-owned page width and padding.
+Create and edit forms follow the canonical `form-workflow` contract in **Guides / Forms / Stacked Form**. Preserve the template-owned page width and padding, and split semantic Groups into named section components.
 
 ```tsx
 function UserCreatePage() {
@@ -332,43 +334,21 @@ function UserCreatePage() {
         description="Identity and access settings for the new account."
       >
         <form className="space-y-3" onSubmit={handleSubmit}>
-          <div className="space-y-1.5">
-            <Label htmlFor="user-name" className="text-xs">
-              Name
-            </Label>
+          <FormField label="Name" htmlFor="user-name">
             <Input id="user-name" className="h-8 text-sm" required />
-          </div>
-          <div className="space-y-1.5">
-            <Label htmlFor="user-email" className="text-xs">
-              Email
-            </Label>
+          </FormField>
+          <FormField label="Email" htmlFor="user-email">
             <Input id="user-email" type="email" className="h-8 text-sm" required />
-          </div>
-          <div className="space-y-1.5">
-            <Label htmlFor="user-role" className="text-xs">
-              Role
-            </Label>
+          </FormField>
+          <FormField label="Role" htmlFor="user-role">
             <Select defaultValue="Viewer">
               <SelectTrigger id="user-role" className="h-8 text-sm">
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>{/* roles */}</SelectContent>
             </Select>
-          </div>
-          <div className="flex justify-end gap-2">
-            <Button
-              type="button"
-              variant="outline"
-              size="sm"
-              className="h-8 text-xs"
-              onClick={() => navigate('/users')}
-            >
-              Cancel
-            </Button>
-            <Button type="submit" size="sm" className="h-8 text-xs">
-              Create user
-            </Button>
-          </div>
+          </FormField>
+          <FormActions onCancel={() => navigate('/users')} submitLabel="Create user" />
         </form>
       </DataBodyTemplate.Group>
     </DataBodyTemplate>
@@ -379,28 +359,57 @@ function UserCreatePage() {
 Form rules:
 
 - Form controls and buttons are `32px` (`h-8`); this differs from the table toolbar's `28px` controls.
-- Use `space-y-3` for the form and `space-y-1.5` within each field.
+- Wrap each field in `FormField`; use `space-y-3` between fields inside the form.
+- End the form in `FormActions`; it already renders the divider and Cancel-before-submit order — do not add a second divider around it.
 - Use the full content width supplied by the stacked group.
-- Do not add `mx-auto`, an arbitrary `max-w-*`, extra horizontal padding, a nested card, or a second action divider.
+- Do not add `mx-auto`, an arbitrary `max-w-*`, extra horizontal padding, or a nested card.
 - The form page owns its mutation. After success, invalidate the narrowest affected queries and navigate to the list or created entity.
 
-## Concise detail Sheet
+## Concise detail SidePanel
 
-Keep the list mounted while showing concise, mostly read-only row information:
+Keep the list mounted while showing concise, mostly read-only row information. Use BaseKit `SidePanelProvider`/`useSidePanel` (`@loykin/side-panel`) — the same package the Kubernetes Workspace guide uses — with DesignKit `PanelTemplate` for the panel body: `title`/`eyebrow` for the header, `PanelTemplate.Section` + `PanelTemplate.Row` for read-only fields, and a `Close` button in `footer` calling `close()`. Do not use DesignKit's own `Sheet` primitive for this, and do not hand-roll a label/value grid with raw `div`/`p` markup.
 
 ```tsx
-<Sheet open={Boolean(selectedUser)} onOpenChange={(open) => !open && clearSelection()}>
-  <SheetContent>
-    <SheetHeader>
-      <SheetTitle>{selectedUser?.name}</SheetTitle>
-      <SheetDescription>User details</SheetDescription>
-    </SheetHeader>
-    {/* concise read-only fields */}
-  </SheetContent>
-</Sheet>
+function UserPanel({ user }: { user: SelectedUser }) {
+  const { close } = useSidePanel()
+  return (
+    <PanelTemplate
+      eyebrow="User"
+      title={user.name}
+      footer={
+        <div className="flex justify-end">
+          <Button variant="outline" size="sm" onClick={() => void close()}>
+            Close
+          </Button>
+        </div>
+      }
+    >
+      <PanelTemplate.Section title="Details">
+        <dl className="space-y-2">
+          <PanelTemplate.Row label="Email">{user.email}</PanelTemplate.Row>
+          <PanelTemplate.Row label="Role">{user.role}</PanelTemplate.Row>
+        </dl>
+      </PanelTemplate.Section>
+    </PanelTemplate>
+  )
+}
+
+function UsersListPage() {
+  const { open } = useSidePanel()
+  return (
+    <SidePanelProvider className="h-full min-h-0">
+      <DataBodyTemplate>
+        <DataGrid
+          /* … */
+          onRowClick={(user) => open(<UserPanel user={user} />, { side: 'right', size: 420, resizable: true })}
+        />
+      </DataBodyTemplate>
+    </SidePanelProvider>
+  )
+}
 ```
 
-If the detail gains editing, multiple sections, complex permissions, a long history, or a need for a shareable URL, replace the Sheet with a detail page. Do not gradually turn the Sheet into a full page inside an overlay.
+If the detail gains editing, multiple sections, complex permissions, a long history, or a need for a shareable URL, replace the SidePanel with a detail page. Do not gradually turn the SidePanel into a full page inside an overlay.
 
 ## Public API boundary
 
@@ -429,7 +438,9 @@ Do not import package-internal source paths. Do not add TanStack Query, React Ro
 - [ ] Table toolbar and pagination controls are `28px` high.
 - [ ] Form controls and buttons are `32px` high.
 - [ ] The stacked form has no arbitrary max-width wrapper or extra action divider.
-- [ ] Create and edit use pages; concise read-only detail uses a Sheet.
+- [ ] The create/edit form uses `FormField` and `FormActions` (see the Stacked Form guide), not hand-rolled label/input or action-row markup.
+- [ ] Create and edit use pages; concise read-only detail uses a SidePanel.
+- [ ] The SidePanel body uses `PanelTemplate` (`title`/`eyebrow` + `PanelTemplate.Section`/`PanelTemplate.Row`), not hand-rolled label/value markup, and DesignKit's own `Sheet` primitive is not used for this.
 - [ ] Complex detail uses a page.
 - [ ] Only public package entry points are imported.
 - [ ] The experience is visually checked in both Sidebar and Header shells.

package/docs/guides/manifest.json

@@ -14,6 +14,32 @@
       ],
       "contract": "managed-table.md"
     },
+    {
+      "id": "kubernetes-workspace",
+      "title": "Operations / Kubernetes Workspace",
+      "summary": "Operational resource collection with quick SidePanel inspection and persistent logs, shell, and events tools in a bottom dock.",
+      "useWhen": [
+        "Kubernetes operations",
+        "resource inspection",
+        "logs and shell",
+        "persistent tool dock"
+      ],
+      "templates": ["DataBodyTemplate", "PanelTemplate"],
+      "playgroundPaths": [
+        "/sidebar/kubernetes-workspace-guide",
+        "/header/kubernetes-workspace-guide"
+      ],
+      "contract": "kubernetes-workspace.md"
+    },
+    {
+      "id": "form-workflow",
+      "title": "Forms / Stacked Form",
+      "summary": "Canonical stacked page structure and modular section boundaries for create, edit, and settings forms.",
+      "useWhen": ["create form", "edit form", "settings form", "multiple form sections"],
+      "templates": ["DataBodyTemplate"],
+      "playgroundPaths": ["/sidebar/form-workflow-guide", "/header/form-workflow-guide"],
+      "contract": "form-workflow.md"
+    },
     {
       "id": "publishing-workflow",
       "title": "Publishing / Blog → Article",

package/docs/guides/publishing-workflow.md

@@ -12,6 +12,8 @@ Use this guide to build a publishing experience where a content collection leads
 
 The existing **Blog Feed** and **Article** template demos are visual references only. This Guide is the supported example of how those page shapes connect.
 
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) first. It governs how this Guide's card grid and article content are built.
+
 ## Route contract
 
 ```text
@@ -37,6 +39,18 @@ Card selection uses React Router navigation. Browser Back returns to the collect
 - Article actions such as Save or Share belong in the article header.
 - Render one page-level template per route. Never put `DetailBodyTemplate` inside `DataBodyTemplate.Body`.
 
+## Card and article presentation
+
+Do not hand-roll the card grid or article body with raw `<div>`/Tailwind. Use these DesignKit components:
+
+- `ArticleCardPreview` — the whole grid card: cover, category, title, excerpt, byline, read time. Pass `coverContent` for per-listing decoration (an icon, an overlay); do not reassemble the card shape from `InteractiveCard` + `ArticleCover` + `ArticleByline` by hand — that duplication is exactly why this component exists (it was copy-pasted near-verbatim between this guide and the Blog Feed demo before being promoted).
+- `ArticleCover` / `ArticleByline` — the cover and byline building blocks `ArticleCardPreview` uses internally. Reach for them directly only outside the card shape, e.g. the article page's hero (`ArticleCover`) and header (`ArticleByline`). `tone` is a semantic value (`'violet' | 'emerald' | 'amber' | 'rose' | 'sky' | 'slate'`), not a raw gradient class string — sample data stores `accent: ArticleTone`, never a Tailwind string.
+- `ArticleBody` — reading-width container with article typography for the article's prose.
+- `ArticleBodySkeleton` — loading placeholder matching `ArticleBody`'s width.
+- `ArticleToc` — the article aside's table of contents.
+
+Article title, excerpt, and category stay as plain content passed into these components; only the reusable shell moves into DesignKit.
+
 ## Deterministic ordering
 
 The mock API returns articles newest first and the GridKit collection declares the same initial published-date sort. In a real API, send sort parameters to the server and include them in the query key. Never sort humanized labels such as “2 hours ago”.
@@ -51,3 +65,6 @@ The mock API returns articles newest first and the GridKit collection declares t
 - [ ] Initial loading is local to the destination content
 - [ ] Existing content remains visible during background refetch
 - [ ] No nested page templates and no article Sheet
+- [ ] The grid card uses `ArticleCardPreview`, not a hand-assembled `InteractiveCard` + `ArticleCover` + `ArticleByline` composition
+- [ ] Article page presentation uses `ArticleBody`/`ArticleBodySkeleton` and `ArticleToc`, not hand-rolled `className` blocks
+- [ ] Sample data stores a semantic `accent`/tone value, never a Tailwind gradient string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loykin/designkit",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A React UI component library with theming support.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -49,6 +49,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@loykin/gridkit": "^0.2.2",
+    "@tanstack/react-table": "^8.21.3",
     "@typescript/native": "npm:typescript@~7.0.2",
     "@types/node": "^26.0.0",
     "@types/react": "^19.2.14",