Added Shade layout primitives

apps/shade/.storybook/preview.tsx

@@ -58,8 +58,19 @@ const preview: Preview = {
 			storySort: {
 				method: 'alphabetical',
 				order: [
-					'Introduction', 'Principles', 'Architecture', 'Tokens', 'Contributing',
-					'Components', 'Layout', 'Experimental'],
+					'Primitives',
+					'Components',
+					'Layout',
+					'Features',
+					'Experimental',
+					'Introduction',
+					'Principles',
+					'Architecture',
+					'Component Rules and Guarantees',
+					'Tokens',
+					'Contributing',
+					'*'
+				],
 			},
 		},
 		docs: {

apps/shade/src/components/layout/error-page.tsx

@@ -6,6 +6,9 @@
     onBackToDashboard?: () => void;
 }
 
+/**
+ * @deprecated Prefer composing product-specific error states from primitives and shared components.
+ */
 const ErrorPage = React.forwardRef<HTMLDivElement, ErrorPageProps>(
     ({className, onBackToDashboard, ...props}, ref) => {
         return (
@@ -24,6 +27,6 @@
     }
 );
 
 ErrorPage.displayName = 'ErrorPage';
 
 export {ErrorPage};

apps/shade/src/components/layout/header.tsx

@@ -1,4 +1,5 @@
 import {H1} from './heading';
+import {Inline} from '@/components/primitives';
 import {cn} from '@/lib/utils';
 import {cva, VariantProps} from 'class-variance-authority';
 
@@ -10,18 +11,20 @@
 
 function HeaderAbove({className, children}: PropsWithChildrenAndClassName) {
     return (
-        <div
-            className={cn('flex items-center gap-2 [grid-area:above]', className)}
+        <Inline
+            align='center'
+            className={cn('[grid-area:above]', className)}
             data-header='header-above'
+            gap='sm'
         >
             {children}
-        </div>
+        </Inline>
     );
 }
 
 function HeaderTitle({className, children}: PropsWithChildrenAndClassName) {
     return (
         <H1
             className={cn(
                 'text-2xl leading-[1.2em] lg:text-3xl [grid-area:title]',
                 className
@@ -29,51 +32,60 @@
             data-header='header-title'
         >
             {children}
         </H1>
     );
 }
 
 function HeaderMeta({className, children}: PropsWithChildrenAndClassName) {
     return (
-        <div
-            className={cn('flex items-center justify-start text-muted-foreground [grid-area:meta] pb-4 pt-1', className)}
+        <Inline
+            align='center'
+            className={cn('text-muted-foreground [grid-area:meta] pb-4 pt-1', className)}
             data-header='header-meta'
+            gap='none'
+            justify='start'
         >
             {children}
-        </div>
+        </Inline>
     );
 }
 
 function HeaderActionGroup({className, children}: PropsWithChildrenAndClassName) {
     return (
-        <div
-            className={cn('flex items-center gap-2', className)}
+        <Inline
+            align='center'
+            className={className}
             data-header='header-action-group'
+            gap='sm'
         >
             {children}
-        </div>
+        </Inline>
     );
 }
 
 function HeaderActions({className, children}: PropsWithChildrenAndClassName) {
     return (
-        <div
-            className={cn('flex items-center gap-4 [grid-area:actions] sm:justify-self-end self-start', className)}
+        <Inline
+            align='center'
+            className={cn('[grid-area:actions] sm:justify-self-end self-start', className)}
             data-header='header-actions'
+            gap='lg'
         >
             {children}
-        </div>
+        </Inline>
     );
 }
 
 function HeaderNav({className, children}: PropsWithChildrenAndClassName) {
     return (
-        <div
-            className={cn('flex items-center gap-2 [grid-area:nav] self-start mt-2 lg:mt-0.5', className)}
+        <Inline
+            align='center'
+            className={cn('[grid-area:nav] self-start mt-2 lg:mt-0.5', className)}
             data-header='header-nav'
+            gap='sm'
         >
             {children}
-        </div>
+        </Inline>
     );
 }
 
@@ -99,6 +111,9 @@
     Meta: typeof HeaderMeta;
 };
 
+/**
+ * @deprecated Prefer composing new header shells with `Grid`, `Inline`, `Stack`, and `Text` primitives.
+ */
 const Header: HeaderComponent = Object.assign(
     React.forwardRef<HTMLElement, HeaderProps>(function Header({className, children, variant}, ref) {
         return (

apps/shade/src/components/layout/heading.tsx

@@ -1,73 +1,110 @@
+import {Text} from '@/components/primitives';
 import {cn} from '@/lib/utils';
 import * as React from 'react';
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface HeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {}
 
+/**
+ * @deprecated Prefer `Text` primitive composition for new heading usage.
+ */
 const H1 = React.forwardRef<HTMLHeadingElement, HeadingProps>(
     ({className, ...props}, ref) => {
         return (
-            <h1
-                ref={ref}
-                className={cn('scroll-m-20 text-3xl leading-[1.1em] tracking-tighter font-bold', className)}
-                {...props} />
+            <Text
+                ref={ref as React.Ref<HTMLElement>}
+                as='h1'
+                className={cn('scroll-m-20 leading-[1.1em] tracking-tighter', className)}
+                size='3xl'
+                weight='bold'
+                {...props}
+            />
         );
     }
 );
 H1.displayName = 'H1';
 
+/**
+ * @deprecated Prefer `Text` primitive composition for new heading usage.
+ */
 const H2 = React.forwardRef<HTMLHeadingElement, HeadingProps>(
     ({className, ...props}, ref) => {
         return (
-            <h2
-                ref={ref}
-                className={cn('scroll-m-20 text-2xl font-bold tracking-tighter first:mt-0', className)}
-                {...props} />
+            <Text
+                ref={ref as React.Ref<HTMLElement>}
+                as='h2'
+                className={cn('scroll-m-20 tracking-tighter first:mt-0', className)}
+                size='2xl'
+                weight='bold'
+                {...props}
+            />
         );
     }
 );
 H2.displayName = 'H2';
 
+/**
+ * @deprecated Prefer `Text` primitive composition for new heading usage.
+ */
 const H3 = React.forwardRef<HTMLHeadingElement, HeadingProps>(
     ({className, ...props}, ref) => {
         return (
-            <h3
-                ref={ref}
-                className={cn('scroll-m-20 text-xl font-semibold tracking-tight', className)}
-                {...props} />
+            <Text
+                ref={ref as React.Ref<HTMLElement>}
+                as='h3'
+                className={cn('scroll-m-20 tracking-tight', className)}
+                size='xl'
+                weight='semibold'
+                {...props}
+            />
         );
     }
 );
 H3.displayName = 'H3';
 
+/**
+ * @deprecated Prefer `Text` primitive composition for new heading usage.
+ */
 const H4 = React.forwardRef<HTMLHeadingElement, HeadingProps>(
     ({className, ...props}, ref) => {
         return (
-            <h4
-                ref={ref}
-                className={cn('scroll-m-20 text-lg font-semibold tracking-tight', className)}
-                {...props} />
+            <Text
+                ref={ref as React.Ref<HTMLElement>}
+                as='h4'
+                className={cn('scroll-m-20 tracking-tight', className)}
+                size='lg'
+                weight='semibold'
+                {...props}
+            />
         );
     }
 );
 H4.displayName = 'H4';
 
 interface HTableProps extends React.HTMLAttributes<HTMLDivElement> {
     children?: React.ReactNode;
     className?: string;
 }
 
+/**
+ * @deprecated Prefer `Text` primitive composition for metadata/label text.
+ */
 const HTable = React.forwardRef<HTMLDivElement, HTableProps>(
     ({className, ...props}, ref) => {
         return (
-            <div
-                ref={ref}
-                className={cn('text-xs text-muted-foreground tracking-wide font-medium uppercase', className)}
-                {...props} />
+            <Text
+                ref={ref as React.Ref<HTMLElement>}
+                as='div'
+                className={cn('tracking-wide uppercase', className)}
+                size='xs'
+                tone='secondary'
+                weight='medium'
+                {...props}
+            />
         );
     }
 );
 HTable.displayName = 'HTable';
 
 export {
     H1,