@loykin/designkit 0.0.4 → 0.0.5

package/docs/guides/README.md

@@ -2,12 +2,15 @@
 
 The Playground's **Guides** group contains complete product flows. Existing template groups remain visual API references; they do not receive an AI guide merely because a workflow uses that template.
 
-| Workflow            | Pattern ID            | Connected destinations                 | Contract                                        |
-| ------------------- | --------------------- | -------------------------------------- | ----------------------------------------------- |
-| Resource Management | `managed-table`       | table → detail Sheet; create/edit page | [Managed Table](./managed-table.md)             |
-| Forms               | `form-workflow`       | create, edit, and settings pages       | [Stacked Form](./form-workflow.md)              |
-| Publishing          | `publishing-workflow` | blog collection → article route        | [Publishing Workflow](./publishing-workflow.md) |
-| Commerce            | `commerce-workflow`   | filtered catalog → product route       | [Commerce Workflow](./commerce-workflow.md)     |
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) before implementing any Guide screen — it defines the mandatory build order (template → slot → component → variant → minimal custom CSS) that every Guide below assumes.
+
+| Workflow            | Pattern ID             | Connected destinations                 | Contract                                          |
+| ------------------- | ---------------------- | -------------------------------------- | ------------------------------------------------- |
+| Resource Management | `managed-table`        | table → detail SidePanel; create/edit page | [Managed Table](./managed-table.md)               |
+| Operations          | `kubernetes-workspace` | Pod table → detail panel → tool dock   | [Kubernetes Workspace](./kubernetes-workspace.md) |
+| Forms               | `form-workflow`        | create, edit, and settings pages       | [Stacked Form](./form-workflow.md)                |
+| Publishing          | `publishing-workflow`  | blog collection → article route        | [Publishing Workflow](./publishing-workflow.md)   |
+| Commerce            | `commerce-workflow`    | filtered catalog → product route       | [Commerce Workflow](./commerce-workflow.md)       |
 
 ## How to use these guides
 

package/docs/guides/ai-ui-implementation-contract.md

@@ -0,0 +1,52 @@
+# AI UI Implementation Contract
+
+This contract applies to every Guide in `docs/guides/`. Read it once, then read the specific Guide for the workflow you are building. It exists because an executable Guide demo teaches by example — an AI session copies what the code *does* more strongly than what the prose *says*. If a Guide's TSX is full of one-off Tailwind, that reads as "styling is done ad hoc here," no matter what the Markdown claims.
+
+## Mandatory implementation order
+
+1. Select the closest executable Guide (`docs/guides/manifest.json`).
+2. Use the page template that Guide documents.
+3. Fill the template's documented slots before creating wrapper layouts.
+4. Use existing DesignKit or bundled shadcn components.
+5. Use an existing named variant for a supported visual difference.
+6. If a visual difference is reusable, add or extend a named component or variant — see `AGENTS.md`'s Implementation Priority.
+7. Use custom CSS only when the requirement is content-specific, integration-specific, and cannot be represented by an existing template, slot, component, or variant.
+
+Custom CSS is not forbidden. It must not read as the default way to build a screen.
+
+## Forbidden patterns
+
+- Reimplementing page-level layout (reading width, article typography, card elevation, section spacing) with raw `<div>` + Tailwind when a DesignKit component or variant already expresses it.
+- Overriding padding, width, typography hierarchy, or responsive behavior that a template already owns.
+- Storing Tailwind utility strings in domain/sample data (e.g. `accent: 'from-violet-500/80 ...'`). Store a semantic value (`accent: 'violet'`) and map it through a component or variant instead — an AI session should never need to invent gradient utility combinations.
+- Copying the same hand-rolled visual pattern into more than one Guide. The second occurrence is the signal to promote it to a component (see `InteractiveCard`, born from the same hover/elevation block appearing in four demos).
+
+## Classifying a `className`/`style` you're about to write
+
+- **Promote to a DesignKit template-level component** if the pattern is reusable across pages regardless of domain: reading width, article typography, metadata rows, table of contents, loading skeletons, elevation/hover behavior, cover/hero layout.
+- **Promote to a named variant** if it's a limited, enumerable visual choice on an existing component: tone, density, elevation, content width, presentation mode.
+- **Keep as local custom CSS** only when all of the following hold: it is content- or integration-specific; it cannot be expressed by an existing template, slot, component, or variant; it does not repeat in another Guide; it does not touch template-owned layout. Justify it inline:
+
+  ```tsx
+  /**
+   * Guide exception:
+   * This third-party renderer requires an explicit container height.
+   * Page spacing, typography, and responsive layout remain owned by DesignKit.
+   */
+  ```
+
+  Custom styling with no such comment should be removed or promoted the next time it's touched.
+
+## Reconstruction checklist (add to every Guide)
+
+- [ ] Existing template slots are used before custom wrapper layouts
+- [ ] Existing DesignKit or shadcn variants/components are used before custom classes
+- [ ] Reusable visual differences are implemented as named components or variants, not repeated `className` blocks
+- [ ] Custom CSS is local, minimal, and explicitly justified with a `Guide exception` comment
+- [ ] No Tailwind utility strings are stored in domain data
+- [ ] Template-owned spacing, width, typography, and responsive behavior are not overridden
+
+## Precedent
+
+- `ArticleCover`, `ArticleByline`, `ArticleToc`, `ArticleBody`, `ArticleBodySkeleton` (`@loykin/designkit`) — extracted from the Publishing guide's hand-rolled article markup; a `tone: ArticleTone` prop replaces raw gradient strings in sample data.
+- `InteractiveCard` (`@loykin/designkit`) — the hover-lift-card treatment duplicated across the Publishing, Commerce, Browse, and Blog Feed demos, promoted to one component.

package/docs/guides/commerce-workflow.md

@@ -12,6 +12,8 @@ Use this guide to build a discovery-to-decision commerce experience. The executa
 
 The existing **Browse / Catalog** and product detail template demos remain visual references. This Guide defines their behavioral connection.
 
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) first. Product cards use DesignKit `InteractiveCard` for the clickable, hover-lifting shell — the same component the Publishing guide uses — not a hand-rolled `<div className="... hover:shadow-md ...">`.
+
 ## Route contract
 
 ```text
@@ -45,3 +47,4 @@ Selecting a product card navigates to the product route. Browser Back and the pr
 - [ ] Product breadcrumb returns to catalog
 - [ ] Purchase action exists only on the product route
 - [ ] No nested page templates and no product Sheet
+- [ ] Product cards use `InteractiveCard`, not a hand-rolled hover/elevation `className` block

package/docs/guides/form-workflow.md

@@ -11,6 +11,8 @@ Use this contract for create, edit, and settings forms. It standardizes the visu
 
 The existing **DataBodyTemplate / Form / Horizontal**, **Stacked**, and **Inline** entries are visual API references. When generating a product form, follow this guide instead of selecting among those demos.
 
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) first.
+
 The executable Playground example uses React Hook Form to demonstrate shared state across modular section components, controlled DesignKit inputs, and field-level errors. React Hook Form is a Playground implementation choice, not a DesignKit dependency or part of this visual contract.
 
 ## Non-negotiable visual contract
@@ -20,10 +22,10 @@ The executable Playground example uses React Hook Form to demonstrate shared sta
 3. Use one `DataBodyTemplate` page root.
 4. Use the stacked form shape for create, edit, and settings pages. Do not switch to `horizontal` or `inline` because the domain changed.
 5. Divide the form into one or more `DataBodyTemplate.Group layout="stacked"` sections according to meaning, not visual preference.
-6. Keep field spacing at `space-y-3`; keep each label/control/help block at `space-y-1.5`.
-7. Use DesignKit controls and the established compact control sizing: `h-8 text-sm` for inputs and selects, `size="sm"` with `h-8 text-xs` for actions.
-8. Put Cancel before the primary submit action. Keep the action cluster right-aligned at the bottom of its save boundary.
-9. Show validation text directly below its field. Show form-level failure above the bottom actions, inside the same form boundary.
+6. Wrap each field in `FormField` (label, control, and `error`/`helperText`) instead of hand-rolling a `space-y-1.5` + `Label` block; keep the fields inside a group at `space-y-3`.
+7. Use DesignKit controls and the established compact control sizing: `h-8 text-sm` for inputs and selects.
+8. End the form in `FormActions` (`status`, `submitLabel`, `onCancel`) instead of hand-rolling the bottom action row — it already puts Cancel before the right-aligned primary submit action and renders the divider above it. Do not add a second divider around it.
+9. Pass validation text to `FormField`'s `error` prop; pass form-level failure to `FormActions`' `status` prop, inside the same form boundary.
 10. A submitting, refreshing, or validation state must not replace or flash the page header or unrelated groups.
 
 ## Module boundary contract
@@ -79,18 +81,14 @@ function IdentitySection() {
       description="Basic account information."
     >
       <div className="space-y-3">
-        <div className="space-y-1.5">
-          <Label htmlFor="member-name" className="text-xs">
-            Name
-          </Label>
+        <FormField label="Name" htmlFor="member-name" error={errors.name?.message}>
           <Input
             id="member-name"
             {...register('name', { required: 'Enter a member name.' })}
             aria-invalid={Boolean(errors.name)}
             className="h-8 text-sm"
           />
-          {errors.name && <p className="text-xs text-destructive">{errors.name.message}</p>}
-        </div>
+        </FormField>
       </div>
     </DataBodyTemplate.Group>
   )
@@ -106,10 +104,7 @@ function AccessSection() {
       description="Default workspace permissions."
     >
       <div className="space-y-3">
-        <div className="space-y-1.5">
-          <Label htmlFor="member-role" className="text-xs">
-            Role
-          </Label>
+        <FormField label="Role" htmlFor="member-role">
           <Controller
             control={control}
             name="role"
@@ -122,7 +117,7 @@ function AccessSection() {
               </Select>
             )}
           />
-        </div>
+        </FormField>
         <Controller
           control={control}
           name="active"
@@ -152,14 +147,7 @@ function MemberForm() {
       <form className="contents" onSubmit={form.handleSubmit(submitMember)}>
         <IdentitySection />
         <AccessSection />
-        <div className="flex justify-end gap-2 border-t border-border pt-(--designkit-panel-gap)">
-          <Button type="button" variant="outline" size="sm" className="h-8 text-xs">
-            Cancel
-          </Button>
-          <Button type="submit" size="sm" className="h-8 text-xs">
-            Save
-          </Button>
-        </div>
+        <FormActions submitLabel="Save" />
       </form>
     </FormProvider>
   )
@@ -210,3 +198,5 @@ function ProfileSettingsSection() {
 - Group count follows the information model; it does not select a different layout.
 - Form and validation libraries remain application choices.
 - Bottom actions belong to the form that they submit.
+- Fields use `FormField`, not a hand-rolled `space-y-1.5` + `Label` block.
+- The bottom action row uses `FormActions`, not a hand-rolled Cancel/submit `div`.

package/docs/guides/kubernetes-workspace.md

@@ -0,0 +1,169 @@
+# Kubernetes Workspace Contract for AI
+
+Use this contract for operational resource browsers where people repeatedly inspect a collection, compare resource state, and open logs or a shell without losing list context.
+
+The executable reference is available at:
+
+- `/sidebar/kubernetes-workspace-guide`
+- `/header/kubernetes-workspace-guide`
+
+The `DataBodyTemplate / Kubernetes` entry is a visual API reference backed by the same composition. The **Guides / Operations / Kubernetes Workspace** entry is the normative workflow contract.
+
+Read [AI UI Implementation Contract](./ai-ui-implementation-contract.md) first.
+
+## 1. Workflow identity
+
+This is one workspace with three distinct interaction layers:
+
+1. The resource table owns discovery, search, filters, refresh, sorting, and selection context.
+2. A right SidePanel owns concise inspection of the selected resource.
+3. A bottom Control Dock owns persistent work such as logs, shell sessions, and cluster events.
+
+Do not flatten these concerns into one table component. Keep query state, selected-resource inspection, and long-running tools independently replaceable.
+
+## 2. Required composition
+
+- Use one `DataBodyTemplate` as the only page-level template.
+- Put GridKit `GlobalSearch` and a BaseKit `FilterInput` (`type: 'select'`, keyed to the namespace column) in the DataGrid header slots. GridKit's own `SelectFilter`/`MultiSelectFilter` do not expose a `size`/`className` prop, so they cannot be sized to match `GlobalSearch`; `FilterInput` can.
+- Use BaseKit `SidePanelProvider` with DesignKit `PanelTemplate` for row inspection. Put `Shell`/`Logs` (and any other panel-opening actions) in `PanelTemplate`'s `actions` slot next to the title, not in `footer` — footer is for closing/committing the panel, not for opening other tools. Render `Close` as a plain icon button (no confirmation) since dismissing a read-only inspection panel is not a destructive action.
+- Use BaseKit `ControlBarProvider` as the tab and persistence model for the bottom dock.
+- Keep Kubernetes API clients, authorization, watches, and mutations in the consuming application.
+- Keep GridKit, `FilterInput`, SidePanel, and Control Bar as application or Playground integrations; they are not DesignKit runtime dependencies.
+
+## 3. Resource collection boundary
+
+Create a named resource component such as `PodsResource`. It owns:
+
+- collection query parameters and result rendering;
+- search and filter state;
+- column definitions and row actions;
+- opening the selected resource in the SidePanel;
+- opening resource tools in the Control Dock.
+
+The route or workspace component owns only cluster context, page hierarchy, providers, and layout. It must not absorb every table and panel implementation detail.
+
+For server-backed data, put search, namespace, sorting, pagination or cursor, and refresh inputs into one query model. Preserve the previous successful result during background refresh when possible. Show initial loading, empty, filtered-empty, permission failure, and refresh failure as distinct states.
+
+## 4. Row interaction contract
+
+Clicking a Pod row opens a read-oriented detail SidePanel. It must not implicitly open logs or start a shell.
+
+The detail panel should show enough information to decide the next action:
+
+- status, readiness, restarts, and age;
+- node, owner/controller, and QoS class;
+- namespace and stable resource name;
+- explicit `Logs` and `Shell` actions.
+
+Use a full detail route only when the resource has deep navigation, editable configuration, history, or a stable URL that users must share. Use the SidePanel for quick inspection that should preserve table position and filters.
+
+Row-level Logs and Shell icon buttons may remain for expert access. They must stop row-click propagation and have accessible names.
+
+## 5. Control Dock contract
+
+Logs, shell sessions, and cluster events are persistent workspace tools, not transient popovers.
+
+- Keep the dock visible at the bottom even with zero tabs.
+- The empty dock is 36px tall and communicates `No active resource panels`.
+- Opening a tool expands the dock to its working height.
+- The dock participates in the workspace flex layout. It must reduce the table region rather than overlap or cover rows.
+- Closing the last tab returns to the empty dock; it does not remove the dock.
+- Deduplicate tools by tool type and resource identity. Reopening an existing Logs or Shell tool activates its tab.
+- Collapsing preserves tabs and active state.
+- Events are cluster-scoped; Logs and Shell are resource-scoped.
+
+The Control Bar package supplies both the tab model (`useControlBar`) and the tab strip chrome (`ControlBar`) — render `<ControlBar />` for the dock header and content instead of hand-building a tab strip. The application still owns domain-specific tool renderers (via `registerTabType`) and any dock action beyond the package's own collapse/expand/fullscreen controls (e.g. an "Events" trigger).
+
+Pass `alwaysVisible` and `emptyState` so the dock stays mounted at zero tabs instead of unmounting: `<ControlBar alwaysVisible emptyState="No active resource panels" />`. Do not hand-build an empty-state wrapper around `ControlBar` — the package owns this directly.
+
+## 6. Spacing and resizing
+
+- The table region must remain `min-height: 0` so it can shrink when the dock expands.
+- The SidePanel must be mounted inside the workspace provider boundary, not around the app shell.
+- The content area's bottom padding must equal its horizontal page padding. A table border touching the viewport edge reads as clipped even when it technically fits.
+- Do not add a second page shell, header, or navigation sidebar inside the demo.
+- Verify the same composition in both SidebarShell and HeaderShell.
+
+## 7. Actions and state
+
+Refresh belongs in the table header because it reloads the collection. Search and namespace filtering belong together without decorative separators that imply unrelated groups.
+
+Do not add aggregate status counters merely to fill header space. Add a summary only when it supports an operational decision and is driven by the same query scope as the table.
+
+For real clusters:
+
+- disable or hide Shell when the user lacks permission;
+- make container selection explicit for multi-container Pods;
+- stream Logs and Shell through cancellable connections;
+- announce connection, reconnecting, and terminal states;
+- clean up watches and streams when their dock tab closes;
+- avoid persisting credentials or log contents in local storage.
+
+## 8. Reference shape
+
+```tsx
+function PodsResource() {
+  const controlBar = useControlBar()
+  const sidePanel = useSidePanel()
+  const query = usePodsQuery()
+
+  const inspectPod = (pod: Pod) => {
+    sidePanel.open(
+      <PodDetailPanel
+        pod={pod}
+        onOpenLogs={() => openPodTool(controlBar, 'logs', pod)}
+        onOpenShell={() => openPodTool(controlBar, 'shell', pod)}
+      />,
+      { side: 'right', size: 420, resizable: true },
+    )
+  }
+
+  return (
+    <DataGrid
+      data={query.data}
+      columns={columns}
+      onRowClick={inspectPod}
+      headerLeft={(table) => (
+        <>
+          <GlobalSearch table={table} />
+          <FilterInput
+            config={namespaceFilterConfig}
+            value={(table.getColumn('namespace')?.getFilterValue() as string) ?? null}
+            onChange={(next) => table.getColumn('namespace')?.setFilterValue(next ?? undefined)}
+          />
+        </>
+      )}
+    />
+  )
+}
+
+function KubernetesWorkspace() {
+  return (
+    <ControlBarProvider persistKey="kubernetes-workspace">
+      <SidePanelProvider className="h-full min-h-0">
+        <div className="flex h-full min-h-0 flex-col overflow-hidden">
+          <DataBodyTemplate>{/* PodsResource */}</DataBodyTemplate>
+          <ControlBar alwaysVisible emptyState="No active resource panels" />
+        </div>
+      </SidePanelProvider>
+    </ControlBarProvider>
+  )
+}
+```
+
+## 9. Review checklist
+
+- [ ] There is exactly one page-level template and one app shell.
+- [ ] Search is GridKit `GlobalSearch` and the namespace control is a BaseKit `FilterInput`, both in the table header.
+- [ ] `GlobalSearch`, `FilterInput`, and any header `Button`s render at the same height and corner radius — verify computed style, not just class names, since GridKit/BaseKit and DesignKit resolve `--radius` independently.
+- [ ] Row click opens a Pod detail SidePanel.
+- [ ] Logs and Shell are explicit actions, not implicit row-click behavior.
+- [ ] Logs, Shell, and any other panel-opening actions live in `PanelTemplate`'s `actions` slot next to the title; `footer` is reserved for closing/committing, and `Close` is a plain icon button, not a confirmation.
+- [ ] Row action buttons stop propagation and have accessible names.
+- [ ] Detail, collection query, and dock tools have separate component/state boundaries.
+- [ ] Tool tabs deduplicate by type and resource identity.
+- [ ] The empty Control Dock remains visible after the final tab closes.
+- [ ] Expanding the dock reflows the table and never overlays it.
+- [ ] Bottom content padding equals horizontal content padding.
+- [ ] Loading, empty, permission, refresh failure, and stream failure states are defined.
+- [ ] The SidebarShell and HeaderShell routes both show exactly one navigation shell.

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 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 Sheet                                     |
+| 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                              |
@@ -33,7 +35,7 @@ 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`                 | `Guides / Forms / Stacked Form`                |
-| Concise read-only inspection                       | `Sheet`                                          | `Managed Table` row detail                     |
+| 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:
@@ -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,23 @@
       ],
       "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",

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.4",
+  "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",