@titan-design/react-ui 0.12.1 → 0.14.0

package/src/components/ui/card/Card.stories.tsx

@@ -15,16 +15,21 @@ import { Button, ButtonText } from '../button'
 const meta: Meta<typeof Card> = {
   title: 'Components/Molecules/Card',
   component: Card,
-  tags: ['autodocs'],
+  parameters: {
+    docs: { description: { component: 'Composes **Surface**.' } },
+  },
+  tags: ['autodocs', 'status:stable', '!status:review'],
   argTypes: {
     variant: {
       control: 'select',
-      options: ['elevated', 'outline', 'filled'],
+      options: ['elevated', 'accent', 'filled', 'outline', 'subtle'],
+      description:
+        'elevated/accent lift with rim + shadow · filled lifts by tone only · outline/subtle stay on the host plane with a hairline edge',
     },
     elevation: {
       control: 'select',
       options: [1, 2, 3],
-      description: 'Elevation level (1=subtle, 2=standard, 3=prominent)',
+      description: 'Planes to lift above the enclosing Surface (default 2: page → card plane)',
     },
     isInteractive: { control: 'boolean' },
     isLoading: { control: 'boolean' },
@@ -128,35 +133,65 @@ export const SimpleCard: Story = {
   ),
 }
 
+// Each level is one more plane up the ramp from the page (base): elevated,
+// raised, overlay. The lift (rim + shadow) grows with the number of planes crossed.
 export const ElevationLevels: Story = {
   render: () => (
     <View style={{ flexDirection: 'row', gap: 16, flexWrap: 'wrap' }}>
       <Card elevation={1} style={{ width: 140 }}>
         <CardContent>
-          <Text className="text-text-primary font-semibold">Subtle (1)</Text>
+          <Text className="text-text-primary font-semibold">1 · elevated</Text>
         </CardContent>
       </Card>
       <Card elevation={2} style={{ width: 140 }}>
         <CardContent>
-          <Text className="text-text-primary font-semibold">Standard (2)</Text>
+          <Text className="text-text-primary font-semibold">2 · raised</Text>
         </CardContent>
       </Card>
       <Card elevation={3} style={{ width: 140 }}>
         <CardContent>
-          <Text className="text-text-primary font-semibold">Prominent (3)</Text>
+          <Text className="text-text-primary font-semibold">3 · overlay</Text>
         </CardContent>
       </Card>
     </View>
   ),
 }
 
+// Depth is relative to the enclosing Surface: the same default Card steps up
+// from wherever it is nested. Inside a card, prefer organising with an inset
+// well or a tone-only `filled` tile over lifting again; a second lift is for a
+// surface that genuinely floats over the first, and it clamps at overlay.
+export const InsideACard: Story = {
+  render: () => (
+    <Card style={{ width: 360 }}>
+      <CardHeader>
+        <CardTitle>Outer · raised</CardTitle>
+        <CardDescription>Two planes up from the page</CardDescription>
+      </CardHeader>
+      <CardContent className="gap-3">
+        <CardInset className="p-3">
+          <Text className="text-text-secondary text-sm">CardInset · one plane down, recessed</Text>
+        </CardInset>
+        <Card variant="filled" elevation={1}>
+          <CardContent>
+            <Text className="text-text-primary text-sm">filled · one plane up, tone only</Text>
+          </CardContent>
+        </Card>
+        <Card>
+          <CardContent>
+            <Text className="text-text-primary text-sm">
+              lifted again · overlay (clamped) — sparingly
+            </Text>
+          </CardContent>
+        </Card>
+      </CardContent>
+    </Card>
+  ),
+}
+
 export const Clickable: Story = {
   render: () => (
-    <Card
-      isInteractive
-      onPress={() => console.log('Card clicked!')}
-      style={{ width: 320 }}
-    >
+    <Card isInteractive onPress={() => console.log('Card clicked!')} style={{ width: 320 }}>
       <CardHeader>
         <CardTitle>Clickable Card</CardTitle>
         <CardDescription>Click anywhere on this card</CardDescription>
@@ -199,49 +234,32 @@ export const Skeleton: Story = {
   ),
 }
 
+// A CardInset is a pressed well one plane DOWN from the card, with the insetWell
+// recess. Nesting one inside another steps down again.
 export const InsetElements: Story = {
   render: () => (
     <View style={{ gap: 16 }}>
-      <Card elevation={2} style={{ width: 320 }}>
+      <Card style={{ width: 320 }}>
         <CardHeader>
           <CardTitle>Card with Inset</CardTitle>
-          <CardDescription>Demonstrating inset elements within cards</CardDescription>
+          <CardDescription>A well one plane below the card</CardDescription>
         </CardHeader>
         <CardContent>
-          <CardInset elevation={-1} className="p-4">
-            <Text className="text-text-secondary text-sm">
-              Shallow inset element (elevation -1)
-            </Text>
-          </CardInset>
-        </CardContent>
-      </Card>
-      
-      <Card elevation={3} style={{ width: 320 }}>
-        <CardHeader>
-          <CardTitle>Deep Inset</CardTitle>
-        </CardHeader>
-        <CardContent>
-          <CardInset elevation={-2} className="p-4">
-            <Text className="text-text-secondary text-sm">
-              Deep inset element (elevation -2)
-            </Text>
+          <CardInset className="p-4">
+            <Text className="text-text-secondary text-sm">Inset element (card − 1)</Text>
           </CardInset>
         </CardContent>
       </Card>
-      
-      <Card elevation={2} style={{ width: 320 }}>
+
+      <Card style={{ width: 320 }}>
         <CardHeader>
           <CardTitle>Nested Insets</CardTitle>
         </CardHeader>
         <CardContent>
-          <CardInset elevation={-1} className="p-4 mb-4">
-            <Text className="text-text-secondary text-sm mb-2">
-              Outer inset (elevation -1)
-            </Text>
-            <CardInset elevation={-2} className="p-3">
-              <Text className="text-text-secondary text-xs">
-                Inner inset (elevation -2)
-              </Text>
+          <CardInset className="p-4 mb-4">
+            <Text className="text-text-secondary text-sm mb-2">Outer inset (card − 1)</Text>
+            <CardInset className="p-3">
+              <Text className="text-text-secondary text-xs">Inner inset (card − 2)</Text>
             </CardInset>
           </CardInset>
         </CardContent>
@@ -268,52 +286,44 @@ export const StatusOutlineCards: Story = {
       <Text className="text-lg font-semibold text-text-primary mb-2">
         Status Cards with Custom Border Colors
       </Text>
-      
+
       <Card variant="outline" borderColor={statusColors.success} style={{ width: 320 }}>
         <CardHeader>
           <CardTitle>Success</CardTitle>
           <CardDescription>Operation completed successfully</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            Your changes have been saved.
-          </Text>
+          <Text className="text-text-secondary">Your changes have been saved.</Text>
         </CardContent>
       </Card>
-      
+
       <Card variant="outline" borderColor={statusColors.error} style={{ width: 320 }}>
         <CardHeader>
           <CardTitle>Error</CardTitle>
           <CardDescription>Something went wrong</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            Please try again or contact support.
-          </Text>
+          <Text className="text-text-secondary">Please try again or contact support.</Text>
         </CardContent>
       </Card>
-      
+
       <Card variant="outline" borderColor={statusColors.warning} style={{ width: 320 }}>
         <CardHeader>
           <CardTitle>Warning</CardTitle>
           <CardDescription>Proceed with caution</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            This action cannot be undone.
-          </Text>
+          <Text className="text-text-secondary">This action cannot be undone.</Text>
         </CardContent>
       </Card>
-      
+
       <Card variant="outline" borderColor={statusColors.info} style={{ width: 320 }}>
         <CardHeader>
           <CardTitle>Information</CardTitle>
           <CardDescription>Good to know</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            New features are available in this release.
-          </Text>
+          <Text className="text-text-secondary">New features are available in this release.</Text>
         </CardContent>
       </Card>
     </View>
@@ -326,10 +336,10 @@ export const StatusFilledCards: Story = {
       <Text className="text-lg font-semibold text-text-primary mb-2">
         Status Cards with Custom Background Colors
       </Text>
-      
-      <Card 
-        variant="outline" 
-        borderColor={statusColors.success} 
+
+      <Card
+        variant="outline"
+        borderColor={statusColors.success}
         bgColor={statusColors.successSubtle}
         style={{ width: 320 }}
       >
@@ -338,15 +348,13 @@ export const StatusFilledCards: Story = {
           <CardDescription>Operation completed successfully</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            Your changes have been saved.
-          </Text>
+          <Text className="text-text-secondary">Your changes have been saved.</Text>
         </CardContent>
       </Card>
-      
-      <Card 
-        variant="outline" 
-        borderColor={statusColors.error} 
+
+      <Card
+        variant="outline"
+        borderColor={statusColors.error}
         bgColor={statusColors.errorSubtle}
         style={{ width: 320 }}
       >
@@ -355,15 +363,13 @@ export const StatusFilledCards: Story = {
           <CardDescription>Something went wrong</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            Please try again or contact support.
-          </Text>
+          <Text className="text-text-secondary">Please try again or contact support.</Text>
         </CardContent>
       </Card>
-      
-      <Card 
-        variant="outline" 
-        borderColor={statusColors.warning} 
+
+      <Card
+        variant="outline"
+        borderColor={statusColors.warning}
         bgColor={statusColors.warningSubtle}
         style={{ width: 320 }}
       >
@@ -372,15 +378,13 @@ export const StatusFilledCards: Story = {
           <CardDescription>Proceed with caution</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            This action cannot be undone.
-          </Text>
+          <Text className="text-text-secondary">This action cannot be undone.</Text>
         </CardContent>
       </Card>
-      
-      <Card 
-        variant="outline" 
-        borderColor={statusColors.info} 
+
+      <Card
+        variant="outline"
+        borderColor={statusColors.info}
         bgColor={statusColors.infoSubtle}
         style={{ width: 320 }}
       >
@@ -389,9 +393,7 @@ export const StatusFilledCards: Story = {
           <CardDescription>Good to know</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            New features are available in this release.
-          </Text>
+          <Text className="text-text-secondary">New features are available in this release.</Text>
         </CardContent>
       </Card>
     </View>
@@ -401,10 +403,8 @@ export const StatusFilledCards: Story = {
 export const BrandColoredCards: Story = {
   render: () => (
     <View style={{ gap: 16 }}>
-      <Text className="text-lg font-semibold text-text-primary mb-2">
-        Brand Colored Cards
-      </Text>
-      
+      <Text className="text-lg font-semibold text-text-primary mb-2">Brand Colored Cards</Text>
+
       <Card
         variant="outline"
         borderColor="var(--color-brand-primary)"
@@ -416,9 +416,7 @@ export const BrandColoredCards: Story = {
           <CardDescription>Orange brand color</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            Card with primary brand color styling.
-          </Text>
+          <Text className="text-text-secondary">Card with primary brand color styling.</Text>
         </CardContent>
       </Card>
 
@@ -433,9 +431,7 @@ export const BrandColoredCards: Story = {
           <CardDescription>Steel brand color</CardDescription>
         </CardHeader>
         <CardContent>
-          <Text className="text-text-secondary">
-            Card with secondary brand color styling.
-          </Text>
+          <Text className="text-text-secondary">Card with secondary brand color styling.</Text>
         </CardContent>
       </Card>
     </View>

package/src/components/ui/card/Card.test.tsx

@@ -11,6 +11,78 @@ import {
   CardSkeleton,
   CardInset,
 } from './Card'
+import { greyRamp } from '../../../theme/tokens/primitives'
+
+// Planes by RAMP STEP, never by literal bytes — see Surface.test.tsx.
+const BASE = greyRamp[925]
+const ELEVATED = greyRamp[900]
+const RAISED = greyRamp[875]
+const OVERLAY = greyRamp[850]
+
+describe('Card depth', () => {
+  it('lifts two planes from the page onto the card plane with rim + shadow', () => {
+    render(<Card testID="card" />)
+    const el = screen.getByTestId('card')
+    expect(el).toHaveStyle({ backgroundColor: RAISED })
+    expect(el.style.boxShadow).toContain('inset 0 1px 0')
+    expect(el.style.boxShadow).toMatch(/0 \d+px \d+px rgba\(0,0,0/)
+  })
+
+  it('is relative: a card nested in a card steps up again and clamps at overlay', () => {
+    render(
+      <Card>
+        <Card testID="inner">
+          <Card testID="innermost" />
+        </Card>
+      </Card>
+    )
+    expect(screen.getByTestId('inner')).toHaveStyle({ backgroundColor: OVERLAY })
+    expect(screen.getByTestId('innermost')).toHaveStyle({ backgroundColor: OVERLAY })
+  })
+
+  it('outline and subtle stay on the host plane with an edge and no lift', () => {
+    render(
+      <>
+        <Card variant="outline" testID="outline" />
+        <Card variant="subtle" testID="subtle" />
+      </>
+    )
+    for (const id of ['outline', 'subtle']) {
+      const el = screen.getByTestId(id)
+      expect(el).toHaveStyle({ backgroundColor: BASE })
+      expect(el.style.boxShadow).toBe('')
+    }
+  })
+
+  it('filled lifts by tone only', () => {
+    render(<Card variant="filled" elevation={1} testID="filled" />)
+    const el = screen.getByTestId('filled')
+    expect(el).toHaveStyle({ backgroundColor: ELEVATED })
+    expect(el.style.boxShadow).toBe('')
+  })
+
+  it('bgColor is the override; a bg-* className is not', () => {
+    render(
+      <>
+        <Card bgColor="#00ff00" testID="bg" />
+        <Card className="bg-surface-overlay" testID="cls" />
+      </>
+    )
+    expect(screen.getByTestId('bg')).toHaveStyle({ backgroundColor: '#00ff00' })
+    expect(screen.getByTestId('cls')).toHaveStyle({ backgroundColor: RAISED })
+  })
+
+  it('CardInset presses one plane down from the card', () => {
+    render(
+      <Card>
+        <CardInset testID="well" />
+      </Card>
+    )
+    const el = screen.getByTestId('well')
+    expect(el).toHaveStyle({ backgroundColor: ELEVATED })
+    expect(el.style.boxShadow).toContain('inset')
+  })
+})
 
 describe('Card', () => {
   it('renders children correctly', () => {
@@ -206,13 +278,15 @@ describe('Card', () => {
       expect(screen.getByText('Inset content')).toBeInTheDocument()
     })
 
-    it('accepts elevation prop', () => {
-      const { container } = render(
-        <CardInset elevation={-2}>
-          <span>Deep inset</span>
-        </CardInset>
+    it('nests: a well inside a well steps down again', () => {
+      render(
+        <Card>
+          <CardInset>
+            <CardInset testID="deeper" />
+          </CardInset>
+        </Card>
       )
-      expect(container).toBeInTheDocument()
+      expect(screen.getByTestId('deeper')).toHaveStyle({ backgroundColor: BASE })
     })
   })