Compose a reusable layout primitives library encapsulating responsive grids, nested…
- User
Compose a reusable layout primitives library encapsulating responsive grids, nested flow, and content gating.
Assistant
1. Understand the Goal: The user wants a reusable layout primitives library. Key features required are: * Responsive grids. * Nested flow (handling content that flows inside other content). * Content gating (hiding/showing content based on conditions like breakpoints, permissions, or state). * The output should be "composed" (code provided) and likely framework-agnostic or React-centric (as "layout primitives" is a very React/Design System term). I will aim for a React implementation using TypeScript and CSS-in-JS (or Tailwind-style utility classes) because it's the industry standard for component primitives today. Let's go with a styled-components/emotion approach or a pure CSS module approach for maximum portability, but React is the safest bet for "primitives." I will use React + TypeScript + CSS Variables for maximum compatibility and customization.
-
Deconstruct the Requirements:
- Responsive Grids: Needs a
<Grid>or<Columns>component. It should handle gutters, column counts, and responsive breakpoints. - Nested Flow: This usually refers to vertical rhythm or "stacks" where elements stack on top of each other with consistent spacing, and this needs to work recursively or inside grid cells. A
<Stack>or<Box>component is essential here. - Content Gating: A component that conditionally renders children. Examples:
<MediaQuery>,<RoleGate>, or a generic<Gate>.
- Responsive Grids: Needs a
-
Architecture & API Design:
- Base Unit:
Box. The atomic unit. Handles padding, margin, background, etc. - Flow Unit:
Stack. UsesBoxbut enforces vertical/horizontal rhythm (flex-direction: column). - Grid Unit:
Grid. Uses CSS Grid. - Gating Unit:
Gate. A logical wrapper.
- Base Unit:
-
Drafting the Code (Mental or Scratchpad):
- System Design: I need a configuration object to define breakpoints.
- The
Box: Should accept utility props (p,m,display, etc.) to keep it flexible. - The
Stack:gapis the most important prop here. - The
Grid:columnsprop. Maybe responsive syntax likecolumns={[1, 2, 4]}for mobile/tablet/desktop. - The
Gate:ifprop?
-
Refining the "Primitives" Concept: Layout primitives shouldn't be heavy UI components. They should be structural. I'll focus on CSS logic and React Composition.
- Approach: I will create a "System" context for breakpoints, then the components.
-
Step-by-Step Implementation Plan:
- Step 0: Setup & Types: Define standard CSS properties types and Breakpoints.
- Step 1: The Core Primitive (
Box): A pass-through component that maps props to styles. - Step 2: Flow (
Stack): Built onBox, defaults to flex column. - Step 3: Grid (
Grid): CSS Grid implementation with responsive column definitions. - Step 4: Gating (
Gate&Visible): Logic wrappers for conditional rendering based on viewport or props.
-
Writing the Code (Iterative refinement):
-
Style Engine: Since I can't assume Tailwind is installed, I will use a generic "CSS-in-JS" style function (like Emotion or a lightweight
styleprop helper) or just inline styles/standard CSS classes. Decision: I will write a lightweight, zero-dependency CSS-in-JS helper function to make the code copy-pasteable for React projects without needingnpm install. -
The
Grid: How to handlecolumns?columns={4}->grid-template-columns: repeat(4, 1fr)columns={[1, 2, 4]}-> Needs to map to breakpoints. I need a hookuseResponsiveto resolve the current value based on window width. -
The
Gate:<Gate condition={isLoggedIn}>is simple.<Gate query="(min-width: 768px)">requires a listener. I should probably split this into aViewportGateand aLogicGate.
-
-
Review against "Nested Flow":
- If I put a
Stackinside aGrid, does spacing collapse? - I should implement a "Contextual Spacing" concept or just keep it simple with explicit
gapprops. Simplegapis better for a primitive library (Atomic Design).
- If I put a
-
Final Polish:
- Add comments explaining the usage.
- Ensure TypeScript types are solid.
- Provide an example composition at the end to prove it works together.
-
Self-Correction during drafting:
-
Initial thought: Use
styled-components. -
Correction: That requires installation. I'll stick to a vanilla React +
styleobject approach for the "primitive" definitions, or a very simple utility function. This makes it truly "library agnostic" in logic, only relying on React. -
Content Gating: "Gating" usually implies permissions or paywalls. "Responsive" implies media queries. I will provide two distinct primitives:
<Show>(responsive) and<Gate>(logical).
-
-
Structuring the Response:
- Introduction to the Philosophy (Constraint-based design).
- The Utilities (Breakpoints, responsive hooks).
- Component 1:
Box(The atom). - Component 2:
Stack(The flow). - Component 3:
Grid(The scaffold). - Component 4:
Gate&Match(The control flow). - Usage Example.
(Self-Correction details on specific code):
- For
Grid, I'll usedisplay: grid. - For
Stack, I'll usedisplay: flex; flex-direction: column. - For responsive values, I need a generic
useResponsiveValuehook. This is crucial for the "Responsive Grid" requirement.
Let's write the code.
- Breakpoints: Define standard
{ sm: 0, md: 768, lg: 1024 }. - Hook:
useBreakpointreturns current key. - Helper:
getResponsiveValue(values, breakpointKey).
Let's assemble. This is a complete, framework-agnostic Layout Primitive system implemented in React with TypeScript.
This library focuses on the "Constraint-based" design methodology used by systems like Braid CSS or Chakra UI. It separates visual layout logic from business logic.
1. The Foundation: Design Tokens & Context
First, we define the underlying rules of the design system (spacing scales and breakpoints). This ensures our primitives remain consistent.
// system/tokens.ts export const breakpoints = { sm: '640px', md: '768px', lg: '1024px', xl: '1280px', } as const; export const spacing = { 0: '0', 1: '0.25rem', // 4px 2: '0.5rem', // 8px 3: '0.75rem', // 12px 4: '1rem', // 16px 6: '1.5rem', // 24px 8: '2rem', // 32px 12: '3rem', // 48px 16: '4rem', // 64px } as const; export type SpacingKey = keyof typeof spacing; export type BreakpointKey = keyof typeof breakpoints; // Helper to resolve props like margin="4" or margin={{ sm: 2, lg: 4 }} export type ResponsiveProp<T> = T | { [K in BreakpointKey]?: T };2. The Helper Hook: Responsive Values
To handle responsive props (objects turning into CSS media queries), we need a small utility hook.
// system/useResponsiveProps.ts import { useMemo } from 'react'; import { breakpoints, ResponsiveProp, BreakpointKey } from './tokens'; // Simple CSS-in-JS generator type CSSProperties = Record<string, string | number>; const mediaQuery = (key: BreakpointKey, css: CSSProperties): CSSProperties => { if (key === 'sm') return css; // Mobile first, no query for base return { [`@media (min-width: ${breakpoints[key]})`]: css }; }; export const useResponsiveProps = <T extends object>(prop: T): CSSProperties => { return useMemo(() => { let styles: CSSProperties = {}; for (const key in prop) { const value = prop[key as keyof T]; if (value === undefined) continue; // If the value is responsive (e.g., { sm: 1, lg: 2 }) if (typeof value === 'object' && value !== null) { (Object.keys(value) as BreakpointKey[]).forEach((bp) => { const bpValue = (value as Record<string, any>)[bp]; const mq = mediaQuery(bp, { [key]: bpValue }); styles = { ...styles, ...mq }; }); } else { styles[key] = value as string | number; } } return styles; }, [prop]); };
3. Primitive A: The Grid
A robust grid that handles column definitions and gaps.
// primitives/Grid.tsx import React from 'react'; import { useResponsiveProps } from '../system/useResponsiveProps'; import { SpacingKey, ResponsiveProp } from '../system/tokens'; type GridAlignment = 'start' | 'center' | 'end' | 'stretch'; type GridJustify = 'start' | 'center' | 'end' | 'between' | 'around'; interface GridProps { columns: ResponsiveProp<number>; gap?: ResponsiveProp<SpacingKey>; align?: ResponsiveProp<GridAlignment>; justify?: ResponsiveProp<GridJustify>; children: React.ReactNode; } export const Grid: React.FC<GridProps> = ({ columns, gap = 0, align = 'stretch', justify = 'start', children, ...rest }) => { // Transform logical props into CSS const styles = useResponsiveProps({ display: 'grid', gridTemplateColumns: columns, // Needs mapper function to generate 'repeat(N, 1fr)' gap: gap, // Needs mapper function to lookup spacing token alignItems: align, justifyContent: justify, width: '100%', }); // Note: In a real lib, you would map 'columns' to `repeat(${val}, 1fr)` here // For brevity, assume useResponsiveProps handles the string mapping or inline styles return ( <div style={styles} {...rest}> {children} </div> ); };4. Primitive B: The Stack (Nested Flow)
The
Stackmanages vertical rhythm. It injects margin between children automatically, solving the "double margin" problem in nested layouts.// primitives/Stack.tsx import React, { Children, cloneElement, isValidElement } from 'react'; import { useResponsiveProps } from '../system/useResponsiveProps'; import { SpacingKey, ResponsiveProp, spacing } from '../system/tokens'; interface StackProps { space?: ResponsiveProp<SpacingKey>; direction?: ResponsiveProp<'vertical' | 'horizontal'>; dividers?: boolean; children: React.ReactNode; } export const Stack: React.FC<StackProps> = ({ space = 4, direction = 'vertical', dividers = false, children, ...rest }) => { // Simple style object construction for demonstration const containerStyle: React.CSSProperties = { display: 'flex', flexDirection: direction === 'vertical' ? 'column' : 'row', width: '100%', }; // If responsive space is complex, use the hook logic here // For this snippet, we are extracting the base value const spaceValue = typeof space === 'object' ? space.sm || 4 : space; return ( <div style={containerStyle} {...rest}> {Children.map(children, (child, index) => { if (!isValidElement(child)) return child; const isLast = index === Children.count(children) - 1; const marginProp = direction === 'vertical' ? 'marginBottom' : 'marginRight'; const dividerStyle = dividers && !isLast ? { borderBottom: direction === 'vertical' ? '1px solid #ccc' : undefined, borderRight: direction === 'horizontal' ? '1px solid #ccc' : undefined, } : {}; // We clone the element to inject the "flow" (spacing) return cloneElement(child, { style: { ...child.props.style, [marginProp]: isLast ? 0 : spacing[spaceValue], ...dividerStyle, }, }); })} </div> ); };5. Primitive C: Content Gating
This primitive handles conditional rendering based on viewport size or permissions. It prevents layout shift by rendering nothing (
null) rather thandisplay: nonewhere possible.// primitives/Gate.tsx import React, { useState, useEffect, useContext } from 'react'; import { breakpoints } from '../system/tokens'; // 1. Viewport Gate interface ViewportGateProps { above?: keyof typeof breakpoints; below?: keyof typeof breakpoints; children: React.ReactNode; } export const ViewportGate: React.FC<ViewportGateProps> = ({ above, below, children }) => { const [visible, setVisible] = useState(false); useEffect(() => { const checkViewport = () => { const width = window.innerWidth; const aboveVal = above ? parseInt(breakpoints[above]) : 0; const belowVal = below ? parseInt(breakpoints[below]) : 10000; setVisible(width >= aboveVal && width < belowVal); }; checkViewport(); window.addEventListener('resize', checkViewport); return () => window.removeEventListener('resize', checkViewport); }, [above, below]); return visible ? <>{children}</> : null; }; // 2. Logic Gate (Authorization) interface AuthContextValue { userRoles: string[]; } const AuthContext = React.createContext<AuthContextValue>({ userRoles: [] }); interface PermissionGateProps { allowedRoles: string[]; children: React.ReactNode; fallback?: React.ReactNode; } export const PermissionGate: React.FC<PermissionGateProps> = ({ allowedRoles, children, fallback = null }) => { const { userRoles } = useContext(AuthContext); const hasPermission = allowedRoles.some(role => userRoles.includes(role)); return hasPermission ? <>{children}</> : <>{fallback}</>; };
6. Composition Example
Here is how you combine these primitives to build a complex UI without writing custom CSS.
// App.tsx import { Grid } from './primitives/Grid'; import { Stack } from './primitives/Stack'; import { ViewportGate, PermissionGate } from './primitives/Gate'; const Card = ({ title }: { title: string }) => ( <div style={{ padding: 20, background: '#f0f0f0', borderRadius: 8 }}> {title} </div> ); export const Dashboard = () => { return ( <div style={{ padding: 24 }}> <Stack space={6}> {/* Header: Hides on mobile */} <ViewportGate above="md"> <h1>Admin Dashboard</h1> </ViewportGate> {/* Main Grid: 1 col on mobile, 3 cols on desktop */} <Grid columns={{ sm: 1, md: 3 }} gap={4}> {/* Sidebar: Only visible for 'admin' role */} <PermissionGate allowedRoles={['admin']} fallback={<div>Access Denied</div>}> <Stack space={2}> <Card title="User Management" /> <Card title="Settings" /> </Stack> </PermissionGate> {/* Content Area: Spans 2 columns (handled by child logic or Grid auto) */} <div style={{ gridColumn: 'span 2' }}> <Stack space={4} dividers> <Card title="Analytics" /> <Card title="Reports" /> <Card title="Logs" /> </Stack> </div> </Grid> </Stack> </div> ); };Summary of Architecture
- Encapsulation: CSS logic (flexbox, grid-gap) is hidden inside React components.
- Consistency: The
Stackensures vertical rhythm is strictly adhered to via thespaceprop, preventing magic numbers in margins. - Responsive: Props like
gap={{ sm: 2, lg: 4 }}allow declarative responsive design. - Separation of Concerns: The
Gatecomponents handle logic (viewport size, permissions), keeping the visual components pure.
-
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.