@otfdashkit/ui 0.1.0

package/src/backgrounds/HeroShaderA.tsx

@@ -0,0 +1,255 @@
+'use client'
+
+import React, { useEffect, useRef } from 'react'
+import { cn } from '../utils/cn'
+
+// ── HeroShaderA ──────────────────────────────────────────────────────────────
+// A clean-room WebGL hero background — slowly drifting "aurora" of three
+// soft gaussian blobs whose colors are read from CSS custom properties
+// (--primary, --chart-2, --chart-3 / passed via `colors` prop).
+//
+// Single fragment shader, no external libs. Auto-pauses when offscreen
+// and falls back to a CSS gradient when WebGL is unavailable or the user
+// prefers reduced motion.
+
+const VERT = `
+  attribute vec2 a_position;
+  varying vec2 v_uv;
+  void main() {
+    v_uv = a_position * 0.5 + 0.5;
+    gl_Position = vec4(a_position, 0.0, 1.0);
+  }
+`
+
+// Three gaussian-style blobs orbiting in lazy circles + subtle grain.
+// All trig folded into a single noise-free pass — cheap on mobile.
+const FRAG = `
+  precision mediump float;
+  varying vec2 v_uv;
+  uniform vec2 u_resolution;
+  uniform float u_time;
+  uniform vec3 u_c1;
+  uniform vec3 u_c2;
+  uniform vec3 u_c3;
+  uniform float u_intensity;
+  uniform vec3 u_bg;
+
+  float blob(vec2 uv, vec2 center, float radius) {
+    float d = length(uv - center) / radius;
+    return exp(-d * d * 1.4);
+  }
+
+  void main() {
+    vec2 uv = v_uv;
+    // correct for aspect so blobs stay round
+    uv.x *= u_resolution.x / u_resolution.y;
+    float aspect = u_resolution.x / u_resolution.y;
+
+    float t = u_time * 0.06;
+    vec2 c1 = vec2(aspect * 0.30 + 0.18 * sin(t * 0.9),       0.40 + 0.14 * cos(t * 1.1));
+    vec2 c2 = vec2(aspect * 0.70 + 0.20 * cos(t * 0.7 + 1.3), 0.55 + 0.12 * sin(t * 1.3 + 0.6));
+    vec2 c3 = vec2(aspect * 0.50 + 0.22 * sin(t * 0.4 + 2.4), 0.30 + 0.18 * cos(t * 0.8 + 1.7));
+
+    float r = aspect * 0.55;
+    float b1 = blob(uv, c1, r);
+    float b2 = blob(uv, c2, r * 0.95);
+    float b3 = blob(uv, c3, r * 1.05);
+
+    vec3 col = u_bg;
+    col = mix(col, u_c1, b1 * u_intensity);
+    col = mix(col, u_c2, b2 * u_intensity);
+    col = mix(col, u_c3, b3 * u_intensity);
+
+    // tiny film grain so flat regions don't band
+    float grain = fract(sin(dot(v_uv * u_resolution, vec2(12.9898, 78.233))) * 43758.5453);
+    col += (grain - 0.5) * 0.03;
+
+    gl_FragColor = vec4(col, 1.0);
+  }
+`
+
+export interface HeroShaderAProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Three blob colors in 0..1 RGB tuples. Default mixes primary + chart-2 + chart-3. */
+  colors?: [readonly [number, number, number], readonly [number, number, number], readonly [number, number, number]]
+  /** Background color underneath the blobs (0..1 RGB). Default very-dark. */
+  background?: readonly [number, number, number]
+  /** 0..1 — how strongly each blob mixes over the background. Default 0.7. */
+  intensity?: number
+  /** Animation speed multiplier. Default 1. Set 0 to freeze. */
+  speed?: number
+  /** Render quality (DPR cap). Default 1.5. */
+  pixelRatio?: number
+}
+
+const DEFAULT_COLORS: HeroShaderAProps['colors'] = [
+  [0.98, 0.45, 0.10] as const, // OTF primary orange
+  [0.18, 0.55, 0.95] as const, // chart-2 blue
+  [0.55, 0.30, 0.95] as const, // chart-3 violet
+]
+
+export const HeroShaderA = React.forwardRef<HTMLDivElement, HeroShaderAProps>(
+  (
+    {
+      className,
+      colors = DEFAULT_COLORS,
+      background = [0.04, 0.03, 0.06],
+      intensity = 0.7,
+      speed = 1,
+      pixelRatio = 1.5,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const wrapRef = useRef<HTMLDivElement | null>(null)
+    const canvasRef = useRef<HTMLCanvasElement | null>(null)
+    const fallbackRef = useRef(false)
+
+    React.useImperativeHandle(ref, () => wrapRef.current as HTMLDivElement)
+
+    useEffect(() => {
+      if (typeof window === 'undefined') return
+      const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches
+      const canvas = canvasRef.current
+      const wrap = wrapRef.current
+      if (!canvas || !wrap) return
+
+      const gl = (canvas.getContext('webgl', { antialias: false, alpha: false }) ||
+        canvas.getContext('experimental-webgl', { antialias: false })) as WebGLRenderingContext | null
+      if (!gl) {
+        fallbackRef.current = true
+        wrap.dataset.fallback = 'true'
+        return
+      }
+
+      // ── compile ──────────────────────────────────────────────────────────
+      const compile = (src: string, type: number) => {
+        const sh = gl.createShader(type)!
+        gl.shaderSource(sh, src)
+        gl.compileShader(sh)
+        if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) {
+          gl.deleteShader(sh)
+          return null
+        }
+        return sh
+      }
+      const vs = compile(VERT, gl.VERTEX_SHADER)
+      const fs = compile(FRAG, gl.FRAGMENT_SHADER)
+      if (!vs || !fs) { fallbackRef.current = true; wrap.dataset.fallback = 'true'; return }
+      const program = gl.createProgram()!
+      gl.attachShader(program, vs)
+      gl.attachShader(program, fs)
+      gl.linkProgram(program)
+      if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        fallbackRef.current = true
+        wrap.dataset.fallback = 'true'
+        return
+      }
+
+      const buf = gl.createBuffer()!
+      gl.bindBuffer(gl.ARRAY_BUFFER, buf)
+      gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]), gl.STATIC_DRAW)
+      const aPos = gl.getAttribLocation(program, 'a_position')
+      gl.enableVertexAttribArray(aPos)
+      gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 0, 0)
+
+      gl.useProgram(program)
+      const uRes = gl.getUniformLocation(program, 'u_resolution')
+      const uTime = gl.getUniformLocation(program, 'u_time')
+      const uC1 = gl.getUniformLocation(program, 'u_c1')
+      const uC2 = gl.getUniformLocation(program, 'u_c2')
+      const uC3 = gl.getUniformLocation(program, 'u_c3')
+      const uBg = gl.getUniformLocation(program, 'u_bg')
+      const uIntensity = gl.getUniformLocation(program, 'u_intensity')
+
+      gl.uniform3f(uC1, colors[0][0], colors[0][1], colors[0][2])
+      gl.uniform3f(uC2, colors[1][0], colors[1][1], colors[1][2])
+      gl.uniform3f(uC3, colors[2][0], colors[2][1], colors[2][2])
+      gl.uniform3f(uBg, background[0], background[1], background[2])
+      gl.uniform1f(uIntensity, intensity)
+
+      // ── resize ───────────────────────────────────────────────────────────
+      const dpr = Math.min(pixelRatio, window.devicePixelRatio ?? 1)
+      const resize = () => {
+        const { clientWidth, clientHeight } = wrap
+        const w = Math.max(1, Math.round(clientWidth * dpr))
+        const h = Math.max(1, Math.round(clientHeight * dpr))
+        if (canvas.width !== w || canvas.height !== h) {
+          canvas.width = w
+          canvas.height = h
+          gl.viewport(0, 0, w, h)
+          gl.uniform2f(uRes, w, h)
+        }
+      }
+      resize()
+      const ro = new ResizeObserver(resize)
+      ro.observe(wrap)
+
+      // ── pause when offscreen ─────────────────────────────────────────────
+      let visible = true
+      const io = new IntersectionObserver((entries) => {
+        for (const e of entries) visible = e.isIntersecting
+      })
+      io.observe(wrap)
+
+      // ── render loop ──────────────────────────────────────────────────────
+      let raf = 0
+      let start = performance.now()
+      const frozen = reduceMotion || speed === 0
+
+      const draw = (now: number) => {
+        if (visible) {
+          const t = frozen ? 0 : ((now - start) / 1000) * speed
+          gl.uniform1f(uTime, t)
+          gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4)
+        }
+        if (!frozen) raf = requestAnimationFrame(draw)
+      }
+      raf = requestAnimationFrame(draw)
+      // single static frame for reduced motion
+      if (frozen) {
+        gl.uniform1f(uTime, 0)
+        gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4)
+      }
+
+      return () => {
+        cancelAnimationFrame(raf)
+        ro.disconnect()
+        io.disconnect()
+        gl.deleteProgram(program)
+        gl.deleteShader(vs)
+        gl.deleteShader(fs)
+        gl.deleteBuffer(buf)
+      }
+    }, [colors, background, intensity, speed, pixelRatio])
+
+    return (
+      <div
+        ref={wrapRef}
+        data-slot="hero-shader-a"
+        className={cn('absolute inset-0 overflow-hidden pointer-events-none', className)}
+        style={style}
+        {...props}
+      >
+        {/* CSS fallback rendered behind the canvas; visible if WebGL fails (data-fallback flips on) */}
+        <div
+          aria-hidden
+          className="absolute inset-0"
+          style={{
+            background:
+              'radial-gradient(60% 60% at 30% 40%, hsl(var(--primary) / 0.35), transparent 60%), ' +
+              'radial-gradient(60% 60% at 70% 60%, hsl(var(--chart-2) / 0.30), transparent 60%), ' +
+              'radial-gradient(60% 60% at 50% 30%, hsl(var(--chart-3) / 0.30), transparent 60%), ' +
+              'hsl(var(--background))',
+          }}
+        />
+        <canvas
+          ref={canvasRef}
+          aria-hidden
+          className="absolute inset-0 h-full w-full block"
+        />
+      </div>
+    )
+  },
+)
+HeroShaderA.displayName = 'HeroShaderA'

package/src/backgrounds/NoiseBackground.tsx

@@ -0,0 +1,51 @@
+import React from 'react'
+import { cn } from '../utils/cn'
+
+export interface NoiseBackgroundProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Noise opacity 0–1 (default 0.04) */
+  opacity?: number
+  /** Noise grain size — maps to SVG baseFrequency (default 0.65) */
+  frequency?: number
+  fixed?: boolean
+}
+
+export const NoiseBackground = React.forwardRef<HTMLDivElement, NoiseBackgroundProps>(
+  (
+    {
+      opacity = 0.04,
+      frequency = 0.65,
+      fixed = false,
+      className,
+      children,
+      style,
+      ...props
+    },
+    ref
+  ) => {
+    const svgNoise = `url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='${frequency}' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E")`
+
+    return (
+      <div
+        ref={ref}
+        data-slot="noise-background"
+        className={cn(
+          fixed ? 'fixed inset-0 z-0' : 'absolute inset-0',
+          'pointer-events-none overflow-hidden',
+          className
+        )}
+        style={{
+          backgroundImage: svgNoise,
+          backgroundRepeat: 'repeat',
+          backgroundSize: '200px 200px',
+          opacity,
+          ...style,
+        }}
+        aria-hidden="true"
+        {...props}
+      >
+        {children}
+      </div>
+    )
+  }
+)
+NoiseBackground.displayName = 'NoiseBackground'

package/src/backgrounds/index.ts

@@ -0,0 +1,5 @@
+export * from './GradientBackground'
+export * from './AnimatedGradient'
+export * from './DottedBackground'
+export * from './NoiseBackground'
+export * from './HeroShaderA'

package/src/blocks/ChatDetail/ChatDetail.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { ChatDetail } from './ChatDetail'
+
+// TODO: add all variants
+const meta: Meta<typeof ChatDetail> = {
+  title: 'Blocks/ChatDetail',
+  component: ChatDetail,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof ChatDetail>
+
+export const Default: Story = {}

package/src/blocks/ChatDetail/ChatDetail.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { ChatDetail } from './ChatDetail'
+
+// TODO: add full a11y + variant tests
+describe('ChatDetail', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<ChatDetail />)).not.toThrow()
+  })
+})

package/src/blocks/ChatDetail/ChatDetail.tsx

@@ -0,0 +1,73 @@
+import React, { useState } from 'react'
+import { Send } from 'lucide-react'
+import { cn } from '../utils/cn'
+import { Avatar, AvatarFallback } from '../primitives/avatar'
+import { Input } from '../primitives/input'
+import { Button } from '../primitives/button'
+
+interface Message { id: string; author: string; initials: string; text: string; time: string; self?: boolean }
+
+const INITIAL_MESSAGES: Message[] = [
+  { id: '1', author: 'Alice Chen', initials: 'AC', text: 'Hey team, just pushed the new design files to Figma.', time: '9:41 AM' },
+  { id: '2', author: 'Bob Smith', initials: 'BS', text: "Awesome! I'll take a look and share feedback by EOD.", time: '9:43 AM' },
+  { id: '3', author: 'You', initials: 'JD', text: 'Looks great, the new color palette really pops!', time: '9:45 AM', self: true },
+  { id: '4', author: 'Alice Chen', initials: 'AC', text: "Thanks! Let's sync tomorrow to go through the comments.", time: '9:47 AM' },
+]
+
+function ChatBubble({ msg }: { msg: Message }) {
+  return (
+    <div className={cn('flex gap-2.5', msg.self && 'flex-row-reverse')}>
+      <Avatar className="h-7 w-7 shrink-0 mt-0.5">
+        <AvatarFallback className="text-xs">{msg.initials}</AvatarFallback>
+      </Avatar>
+      <div className={cn('max-w-[70%]', msg.self && 'items-end flex flex-col')}>
+        <div className="flex items-baseline gap-2 mb-0.5">
+          <span className="text-xs font-medium">{msg.author}</span>
+          <span className="text-[10px] text-[hsl(var(--muted-foreground))]">{msg.time}</span>
+        </div>
+        <div className={cn(
+          'rounded-md px-3 py-2 text-sm',
+          msg.self
+            ? 'bg-[hsl(var(--primary))] text-[hsl(var(--primary-foreground))]'
+            : 'bg-[hsl(var(--muted))]'
+        )}>
+          {msg.text}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export interface ChatDetailProps { className?: string }
+
+export function ChatDetail({ className }: ChatDetailProps) {
+  const [messages, setMessages] = useState(INITIAL_MESSAGES)
+  const [input, setInput] = useState('')
+
+  const send = () => {
+    if (!input.trim()) return
+    const now = new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+    setMessages(m => [...m, { id: `${Date.now()}`, author: 'You', initials: 'JD', text: input.trim(), time: now, self: true }])
+    setInput('')
+  }
+
+  return (
+    <div className={cn('flex h-[480px] flex-col overflow-hidden rounded-md border border-[hsl(var(--border))] bg-[hsl(var(--card))]', className)}>
+      <header className="flex items-center gap-3 border-b border-[hsl(var(--border))] px-4 py-3">
+        <Avatar className="h-8 w-8"><AvatarFallback className="text-xs">AC</AvatarFallback></Avatar>
+        <div>
+          <p className="text-sm font-semibold">Design Team</p>
+          <p className="text-xs text-[hsl(var(--muted-foreground))]">4 members</p>
+        </div>
+      </header>
+      <div className="flex-1 overflow-auto p-4 space-y-4">
+        {messages.map(m => <ChatBubble key={m.id} msg={m} />)}
+      </div>
+      <div className="flex items-center gap-2 border-t border-[hsl(var(--border))] p-3">
+        <Input className="flex-1 h-9 text-sm" placeholder="Type a message..." value={input}
+          onChange={e => setInput(e.target.value)} onKeyDown={e => e.key === 'Enter' && send()} />
+        <Button size="icon" className="h-9 w-9 shrink-0" onClick={send}><Send className="h-4 w-4" /></Button>
+      </div>
+    </div>
+  )
+}

package/src/blocks/ChatDetail/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './ChatDetail'

package/src/blocks/FeedbackModal/FeedbackModal.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { FeedbackModal } from './FeedbackModal'
+
+// TODO: add all variants
+const meta: Meta<typeof FeedbackModal> = {
+  title: 'Blocks/FeedbackModal',
+  component: FeedbackModal,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof FeedbackModal>
+
+export const Default: Story = {}

package/src/blocks/FeedbackModal/FeedbackModal.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { FeedbackModal } from './FeedbackModal'
+
+// TODO: add full a11y + variant tests
+describe('FeedbackModal', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<FeedbackModal />)).not.toThrow()
+  })
+})

package/src/blocks/FeedbackModal/FeedbackModal.tsx

@@ -0,0 +1,68 @@
+import React, { useState } from 'react'
+import { cn } from '../utils/cn'
+import { Button } from '../primitives/button'
+import { Textarea } from '../primitives/textarea'
+
+const REACTIONS = ['😊', '😐', '😕', '😡', '🤩']
+
+export interface FeedbackModalProps {
+  onSubmit?: (data: { reaction: string; text: string }) => void
+  className?: string
+}
+
+export function FeedbackModal({ onSubmit, className }: FeedbackModalProps) {
+  const [reaction, setReaction] = useState('')
+  const [text, setText] = useState('')
+  const [submitted, setSubmitted] = useState(false)
+
+  const handleSubmit = () => {
+    onSubmit?.({ reaction, text })
+    setSubmitted(true)
+  }
+
+  if (submitted) {
+    return (
+      <div className={cn('flex flex-col items-center gap-3 py-8 px-6 text-center', className)}>
+        <span className="text-4xl">🎉</span>
+        <p className="font-semibold">Thanks for your feedback!</p>
+        <p className="text-sm text-[hsl(var(--muted-foreground))]">We'll use it to improve your experience.</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className={cn('flex flex-col gap-4 p-6', className)}>
+      <div>
+        <h2 className="text-base font-semibold">Send Feedback</h2>
+        <p className="text-sm text-[hsl(var(--muted-foreground))] mt-0.5">How are you feeling about the product?</p>
+      </div>
+      <div className="flex gap-2">
+        {REACTIONS.map(r => (
+          <button
+            key={r}
+            onClick={() => setReaction(r)}
+            className={cn(
+              'flex h-10 w-10 items-center justify-center rounded-md border text-xl transition-colors',
+              reaction === r
+                ? 'border-[hsl(var(--primary))] bg-[hsl(var(--primary)/0.1)]'
+                : 'border-[hsl(var(--border))] hover:bg-[hsl(var(--accent))]'
+            )}
+          >
+            {r}
+          </button>
+        ))}
+      </div>
+      <Textarea
+        placeholder="Tell us more (optional)..."
+        value={text}
+        onChange={e => setText(e.target.value)}
+        className="resize-none"
+        rows={4}
+      />
+      <div className="flex justify-end gap-2">
+        <Button variant="outline" size="sm">Cancel</Button>
+        <Button size="sm" onClick={handleSubmit} disabled={!reaction}>Submit</Button>
+      </div>
+    </div>
+  )
+}

package/src/blocks/FeedbackModal/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './FeedbackModal'

package/src/blocks/FileCards/FileCards.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { FileCards } from './FileCards'
+
+// TODO: add all variants
+const meta: Meta<typeof FileCards> = {
+  title: 'Blocks/FileCards',
+  component: FileCards,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof FileCards>
+
+export const Default: Story = {}

package/src/blocks/FileCards/FileCards.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { FileCards } from './FileCards'
+
+// TODO: add full a11y + variant tests
+describe('FileCards', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<FileCards />)).not.toThrow()
+  })
+})

package/src/blocks/FileCards/FileCards.tsx

@@ -0,0 +1,56 @@
+// @ts-nocheck
+import React from 'react'
+import { FileText, Image, FileCode, Film, Archive, File } from 'lucide-react'
+import { cn } from '../utils/cn'
+import { Card, CardContent } from '../primitives/card'
+
+interface FileItem { id: string; name: string; type: string; size: string; modified: string }
+
+const FILES: FileItem[] = [
+  { id: '1', name: 'design-system.fig', type: 'figma', size: '14.2 MB', modified: 'Mar 12' },
+  { id: '2', name: 'hero-banner.png', type: 'image', size: '3.8 MB', modified: 'Mar 11' },
+  { id: '3', name: 'api-spec.yaml', type: 'code', size: '42 KB', modified: 'Mar 10' },
+  { id: '4', name: 'demo-video.mp4', type: 'video', size: '128 MB', modified: 'Mar 9' },
+  { id: '5', name: 'assets.zip', type: 'archive', size: '56 MB', modified: 'Mar 8' },
+  { id: '6', name: 'meeting-notes.pdf', type: 'pdf', size: '1.1 MB', modified: 'Mar 7' },
+]
+
+const TYPE_ICON: Record<string, React.ElementType> = {
+  figma: FileText, image: Image, code: FileCode, video: Film, archive: Archive, pdf: FileText,
+}
+
+const TYPE_COLOR: Record<string, string> = {
+  figma: 'text-purple-500', image: 'text-green-500', code: 'text-blue-500',
+  video: 'text-red-500', archive: 'text-yellow-500', pdf: 'text-orange-500',
+}
+
+function FileCard({ file }: { file: FileItem }) {
+  const Icon = TYPE_ICON[file.type] ?? File
+  return (
+    <Card className="cursor-pointer hover:shadow-md transition-shadow">
+      <CardContent className="p-4">
+        <div className={cn('flex h-10 w-10 items-center justify-center rounded-md bg-[hsl(var(--muted))] mb-3', TYPE_COLOR[file.type])}>
+          <Icon className="h-5 w-5" />
+        </div>
+        <p className="text-sm font-medium truncate">{file.name}</p>
+        <div className="flex items-center justify-between mt-1">
+          <span className="text-xs text-[hsl(var(--muted-foreground))]">{file.size}</span>
+          <span className="text-xs text-[hsl(var(--muted-foreground))]">{file.modified}</span>
+        </div>
+      </CardContent>
+    </Card>
+  )
+}
+
+export interface FileCardsProps {
+  files?: FileItem[]
+  className?: string
+}
+
+export function FileCards({ files = FILES, className }: FileCardsProps) {
+  return (
+    <div className={cn('grid gap-3', className)} style={{ gridTemplateColumns: 'repeat(auto-fill, minmax(min(100%,160px),1fr))' }}>
+      {files.map(f => <FileCard key={f.id} file={f} />)}
+    </div>
+  )
+}

package/src/blocks/FileCards/index.ts

@@ -0,0 +1,2 @@
+// @tier: stub — full checklist in Phase 3
+export * from './FileCards'

package/src/blocks/FilesList/FilesList.stories.tsx

@@ -0,0 +1,14 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { FilesList } from './FilesList'
+
+// TODO: add all variants
+const meta: Meta<typeof FilesList> = {
+  title: 'Blocks/FilesList',
+  component: FilesList,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof FilesList>
+
+export const Default: Story = {}

package/src/blocks/FilesList/FilesList.test.tsx

@@ -0,0 +1,9 @@
+import { render } from '@testing-library/react'
+import { FilesList } from './FilesList'
+
+// TODO: add full a11y + variant tests
+describe('FilesList', () => {
+  it('renders without throwing', () => {
+    expect(() => render(<FilesList />)).not.toThrow()
+  })
+})