stamp context style Command

Generate context bundles that include style metadata. This extracts visual and layout info from your React components so AI assistants can understand your design.

• [path] (optional) – Directory to scan. Defaults to the current working directory. Paths can be relative (./src) or absolute.

Note: The stamp context style command is equivalent to stamp context --include-style. Both syntaxes produce identical output.

File Exclusion: stamp context style respects .stampignore, just like stamp context. .stampignore is completely optional and independent of security scanning. See stampignore.md for details.

Overview

stamp context style adds visual and layout info on top of the component logic and structure that stamp context extracts. This lets AI assistants:

• Understand the visual design of components
• Suggest visually consistent components
• Analyze layout patterns (flex, grid, responsive breakpoints)
• Track color palettes and spacing patterns
• Identify animation and motion usage

What It Extracts

It extracts four types of metadata:

1. Style Sources

Identifies which styling approaches are used in each component:

• Tailwind CSS – Extracts and categorizes utility classes:

  • Layout (flex, grid, block, container)
  • Spacing (padding, margin, gap utilities)
  • Sizing (width, height, min/max constraints)
  • Typography (text size, font weight, line height)
  • Colors (background, text, border colors)
  • Borders (border styles, radius)
  • Effects (shadows, opacity, filters)
  • Transitions and animations
  • Responsive breakpoints (sm, md, lg, xl, 2xl)

• SCSS/CSS Modules – Detects module imports from TSX/TS files and parses the imported style files using AST-based parsing (css-tree):

  • CSS selectors used (class, ID, and type selectors)
  • CSS properties defined
  • SCSS feature detection (variables, nesting, mixins as boolean flags)
  • Nested rules inside @media, @supports, @container, and other at-rules
  • Note: Only CSS/SCSS files that are imported by component files are parsed. Standalone CSS/SCSS files that aren't imported won't be analyzed.

• Inline Styles – Extracts inline style objects with:

  • CSS property names (e.g., ['animationDelay', 'color', 'padding'])
  • Literal property values (e.g., { animationDelay: '2s', color: 'blue' })
  • Dynamic values (variables, function calls) are detected as properties but values are not extracted (static analysis limitation)

• Styled JSX – Extracts CSS content from <style jsx> blocks:

  • Full CSS content extraction from template literals
  • CSS selector extraction (parsed using css-tree AST)
  • CSS property extraction
  • Global attribute detection (<style jsx global>)
  • Support for template literals, string literals, and tagged template expressions

• styled-components/Emotion – Identifies (via AST-based extraction):

  • Styled component declarations (styled.div, styled(Component), styled('div'))
  • Theme usage (props.theme, useTheme() hook)
  • CSS prop usage (Emotion)
  • Precise import verification (only matches styled-components/Emotion, not MUI styled)

• framer-motion – Detects:

  • Motion components (motion.div, motion.button, etc.)
  • Animation variants
  • Gesture handlers
  • Layout animations
  • Viewport-triggered animations

• Material UI – Detects:

  • Material UI components used (Button, TextField, Card, etc.)
  • Material UI packages imported (@mui/material, @material-ui/core, etc.)
  • Theme usage (useTheme, ThemeProvider, createTheme)
  • sx prop usage for styling
  • styled from @mui/material/styles
  • makeStyles (legacy styling)
  • System props on Box/Stack components

• Ant Design – Detects:

  • Ant Design components used (Button, Card, Form, Input, Table, etc.)
  • Ant Design packages imported (antd, @ant-design/*)
  • Theme usage (useToken, ConfigProvider, getDesignToken)
  • ConfigProvider usage for app-wide configuration
  • Form usage (Form, Form.Item, Form.List)
  • Locale/internationalization usage (useLocale, getLocale)
  • Icons usage (@ant-design/icons)
  • Subpath imports (antd/es/*)

• Chakra UI – Detects:

  • Chakra UI components used (Button, Card, Box, Stack, Input, etc.)
  • Chakra UI packages imported (@chakra-ui/*)
  • Theme usage (useTheme, ChakraProvider, extendTheme)
  • Color mode usage (useColorMode, useColorModeValue, ColorModeScript)
  • Responsive props (array syntax: [base, md, lg])
  • System props on layout components (Box, Stack, Flex, Grid, etc.)

• ShadCN/UI – Detects:

  • ShadCN/UI components used (Button, Card, Dialog, Sheet, etc.)
  • Component imports from typical ShadCN paths (@/components/ui/, ~/components/ui/, etc.)
  • Variant prop usage (default, destructive, outline, secondary, etc.)
  • Size prop usage (sm, lg, icon, etc.)
  • Form integration (react-hook-form)
  • Theme usage (next-themes, dark mode)
  • Icon library usage (lucide-react, @radix-ui/react-icons, react-icons)
  • Component density (low, medium, high based on component count)

• Radix UI – Detects:

  • Radix UI primitives used (Dialog, Popover, DropdownMenu, etc.)
  • Package imports (@radix-ui/react-*)
  • Controlled vs uncontrolled component patterns
  • Portal usage for overlays
  • asChild composition pattern
  • Accessibility features (RTL/LTR support, focus management, keyboard navigation, modal dialogs)
  • Composition depth (simple, moderate, complex)

Component Ranking and Limits

Component libraries (Material UI, Chakra UI, Ant Design, ShadCN) extract components using a frequency-based ranking system:

How it works:

1. Detection: Components are detected from:

   • Import statements: import { Button, Box } from '@chakra-ui/react' (always counted)
   • JSX usage: <Button>, <Box>, etc. (only counted if imports from the library are detected first)

2. Counting: Each component occurrence increments its count:

   import { Button, Box, Text } from '@chakra-ui/react'; function MyComponent() { return ( <> <Button>1</Button> // Button: +1 (import) + 1 (JSX) = 2 <Button>2</Button> // Button: +1 = 3 <Button>3</Button> // Button: +1 = 4 <Box p={4} /> // Box: +1 (import) + 1 (JSX) = 2 <Text>Hello</Text> // Text: +1 (import) + 1 (JSX) = 2 </> ); }

   Final counts: Button: 4, Box: 2, Text: 2

3. Ranking: Components are sorted by:

   • Usage frequency (highest count first)
   • Alphabetically (when counts are tied)

   Result: ['Button', 'Box', 'Text'] (Button has highest count; Box comes before Text alphabetically)

4. Limiting: Only the top N components are returned:

   • Material UI, Chakra UI, Ant Design: Top 20 components
   • ShadCN: Top 30 components (accommodates composable nature)
   • Styled Components: Top 10 styled component declarations

Why limits? Component lists are limited to keep context bundles focused and token-efficient. The most frequently used components are typically the most important for understanding the codebase, so limiting to the top N ensures you get the most relevant information without token bloat.

Note: Only components from predefined lists (e.g., CHAKRA_COMPONENTS, ANT_COMPONENTS) that are actually used in the file are extracted. Unused imports or non-library components are not included.

2. Layout Metadata

Extracts structural layout information using AST-based analysis. All layout extraction handles variant-prefixed classes (e.g., md:flex, lg:grid) and dynamic className expressions (e.g., className={cn('flex')}, className={grid ${cols}}).

• Layout Type – Identifies flex or grid layouts (grid takes precedence if both are present)
• Grid Patterns – Extracts column configurations (e.g., "2 3" from "grid-cols-2 md:grid-cols-3")
• Hero Patterns – Detects hero sections (large text + CTA buttons)
• Feature Cards – Identifies grid layouts with card-like elements

3. Visual Metadata

Captures visual design patterns using AST-based extraction. All visual extraction handles variant-prefixed classes (e.g., md:bg-blue-500, dark:text-slate-50, lg:px-4).

• Color Palette – Extracts color classes (bg-, text-, border-*)
• Spacing Patterns – Identifies padding and margin utilities. Supports all Tailwind formats: integers (p-4), fractions (p-1.5), named (p-px), arbitrary (p-[2px]), negative (-mt-2)
• Border Radius – Detects rounded corner patterns, stores token value (e.g., "lg" from "rounded-lg"). Valid values: "default", "sm", "md", "lg", "xl", "2xl", "3xl", "full"
• Typography – Extracts text size and font weight classes

4. Animation Metadata

Identifies animation and motion usage:

• Animation Library – framer-motion or CSS
• Animation Type – fade-in, slide, etc.
• Trigger Type – inView, hover, click, etc.

Options

All options from stamp context are supported except --compare-modes. The style command accepts the same flags. Note: --compare-modes is not available for stamp context style; use stamp context --compare-modes instead to analyze token costs.

Example Workflows

Style Mode: Lean vs Full

The --style-mode flag controls how style metadata is formatted in the output. Both modes extract the same data; the difference is how much is included in the output.

• lean (default) – Compact format: drops arrays, keeps counts and flags:

  • Tailwind: classCount instead of full class arrays
  • Component libraries: Top N components with counts
  • More token-efficient, suitable for most use cases

• full – Verbose format: keeps all extracted data (arrays of classes, selectors, components, etc.):

  • Tailwind: Full arrays of classes in each category
  • Component libraries: Complete component lists with all details
  • More comprehensive, useful for detailed design analysis

When to use each mode:

• Use lean (default) when:

  • You want token-efficient context bundles
  • You need basic style awareness for AI assistants
  • You're working with large codebases

• Use full when:

  • You need complete style information for design system analysis
  • You're doing detailed visual pattern analysis
  • Token cost is not a primary concern

Output Format

Style metadata is included in the style field of each component's contract within the context bundle. The structure follows this schema:

Style Metadata Fields

styleSources

Object containing detected styling approaches:

• tailwind – Object with categorized classes, breakpoints, and class count
• scssModule / cssModule – Path to module file (if imported)
• scssDetails / cssDetails – Parsed details from style files
• inlineStyles – Can be boolean (legacy) or object with properties (array) and values (record of property-value pairs)
• styledJsx – Object with css (extracted CSS content), global (boolean), selectors (array), and properties (array)
• styledComponents – Object with component names and theme usage
• motion – Object with framer-motion components and features
• materialUI – Object with Material UI components, packages, and styling features
• antd – Object with Ant Design components, packages, and features (theme, ConfigProvider, form, locale, icons)
• chakraUI – Object with Chakra UI components, packages, and features (theme, color mode, responsive props, system props)
• shadcnUI – Object with ShadCN/UI components, variants, sizes, and features (form integration, theme, icons, component density)
• radixUI – Object with Radix UI primitives (organized by package), patterns (controlled/uncontrolled, portals, asChild), accessibility features, and composition depth

layout

Layout structure information (AST-based extraction):

• type – "flex" or "grid" (grid takes precedence if both are present)
• cols – Grid column numbers (e.g., "2 3" extracted from "grid-cols-2 md:grid-cols-3")
• hasHeroPattern – Boolean indicating hero section pattern (large text + CTA buttons)
• hasFeatureCards – Boolean indicating feature card grid pattern

Layout extraction uses AST analysis, so it handles dynamic className expressions (cn(), clsx()), variant-prefixed classes, and conditional expressions.

visual

Visual design patterns (AST-based extraction):

• colors – Array of color utility classes (sorted, limited to top 10)
• spacing – Array of spacing utility classes (sorted, limited to top 10). Supports all formats: p-4, p-1.5, p-px, p-[2px], -mt-2
• radius – Most common border radius token (e.g., "lg" from "rounded-lg"). Valid values: "default", "sm", "md", "lg", "xl", "2xl", "3xl", "full"
• typography – Array of typography classes (sorted, limited to top 10)

Visual extraction uses AST analysis, so it handles dynamic className expressions (cn(), clsx()), variant-prefixed classes, and template literals (static segments extracted).

animation

Animation and motion information:

• library – "framer-motion" or "css"
• type – Animation type (e.g., "fade-in")
• trigger – Trigger type (e.g., "inView", "hover")

Style metadata is only included when style information is detected. Components without style usage won't have a style field.

Use Cases

Design System Analysis

Understand visual patterns across your codebase:

Then analyze the output to:

• Track color palette usage across components
• Identify spacing pattern consistency
• Find components using similar layout patterns
• Detect animation usage patterns

AI-Assisted Design

Enable AI assistants to suggest visually consistent components:

Layout Understanding

Help AI understand component structure:

AI assistants can now:

• Understand flex vs grid layouts
• Recognize responsive breakpoint usage
• Identify hero sections and feature card grids
• Suggest layout improvements

Animation Detection

Identify components with motion:

The output helps you:

• Find all components using framer-motion
• Track animation patterns across the codebase
• Identify viewport-triggered animations
• Understand gesture handler usage

Style Consistency

Track design system adherence:

Use the output to:

• Verify color palette consistency
• Check spacing pattern usage
• Ensure typography scale adherence
• Monitor border radius patterns

Integration with Other Commands

Validation

Style metadata is validated along with the rest of the context:

Comparison

Style metadata is included in drift detection:

The compare command will detect changes in:

• Style sources (added/removed Tailwind classes, etc.)
• Layout patterns
• Visual metadata
• Animation configurations

Watch Mode

Watch mode works with style metadata extraction, monitoring both code and style files:

Watched file types:

• .ts, .tsx (always)
• .css, .scss, .module.css, .module.scss (with style extraction)

When you edit a style file that's imported by a component, watch mode will:

1. Detect the change
2. Re-extract style metadata for affected components
3. Rebuild only the affected bundles
4. Show what changed in the style metadata

Using watch-fast profile:

For faster rebuilds during development, use the watch-fast profile which applies lighter style extraction:

For comprehensive watch mode documentation, see watch.md.

Token Impact

Style metadata adds a small token overhead to context bundles. Note: --compare-modes is not available for stamp context style. Use stamp context --compare-modes (without the style subcommand) to see the token impact across different modes.

The --compare-modes flag automatically regenerates contracts with and without style metadata to show tokenizer-based or approximate token counts (see compare-modes.md for Claude caveats). This shows you:

• Token overhead of including style metadata (header vs header+style)
• Comparison across all modes – none, header, header+style, and full
• Savings percentages compared to both raw source and full context

See compare-modes.md for a comprehensive guide to token cost analysis and mode comparison.

Example output:

In this example, including style metadata adds approximately 1,667 GPT-4 tokens (13,895 - 12,228) or about 13.6% overhead compared to header-only mode.

Tips

• Start with default – The default header code mode works well for most use cases
• Use profiles – Combine with --profile llm-safe for token-constrained scenarios
• Incremental updates – Style metadata is included in folder-based context files, enabling incremental regeneration
• CI integration – Use --stats to track style metadata size in CI pipelines
• Design reviews – Generate style context before design system reviews to understand current patterns

Error Handling

The style extractor is designed to be robust and will never crash the CLI, even when encountering:

• Missing files: SCSS/CSS module files that don't exist are silently skipped
• Malformed code: Invalid JSX, TypeScript syntax errors, or parse failures are handled gracefully
• Extractor failures: If one style extractor fails (e.g., Material UI parsing), others continue to work and return partial results
• AST traversal errors: Complex or malformed code that causes AST parsing issues falls back gracefully
• Invalid file paths: Non-existent directories or invalid paths are handled without crashing

Partial Results

The extractor is designed to return partial results rather than failing completely. This means:

• If Tailwind extraction fails, other extractors (styled-components, Material UI, etc.) still work
• If SCSS file parsing fails, other style sources are still extracted
• If layout metadata extraction fails, visual and animation metadata can still be extracted
• The main function returns undefined only when no style information is found (which is expected behavior)

Debug Logging

All error handling is silent by default. To enable debug logging for troubleshooting, set the LOGICSTAMP_DEBUG=1 environment variable:

This will output detailed error messages to help identify problematic files or expressions:

Best Practices

• Don't worry about missing files: If a component imports a style file that doesn't exist, the extractor will skip it and continue
• Check debug logs when issues occur: Enable LOGICSTAMP_DEBUG=1 if you suspect extraction problems
• Expect partial results: Some extraction failures are normal (e.g., runtime-generated classes can't be statically analyzed)

Limitations

• Dynamic class values – While AST extraction handles cn(), clsx(), and template literals, classes generated from runtime variables (e.g., className={styles[someVar]}) are not detected
• CSS-in-JS – All major CSS-in-JS libraries are supported: styled-components, Emotion, Material UI, ShadCN/UI, Radix UI, Framer Motion, Styled JSX, Chakra UI, and Ant Design (v0.5.1+). Schema validation fixes for these fields included in v0.5.2. Detection uses AST-based extraction for accurate pattern matching.
• External stylesheets – Global CSS files are not analyzed; only CSS/SCSS files imported by TSX/TS component files are parsed. Standalone CSS/SCSS files that aren't imported won't be scanned.
• Runtime styles – Styles applied via JavaScript at runtime are not detected
• Template literal dynamic segments – Phase 1 (v0.3.9+) extracts classes from variables, object properties, and conditionals within template literals. Phase 2 patterns (object lookups with variables like variants[variant], cross-file references, function calls) are not yet resolved.

Examples

Basic Usage

With Custom Options

Related Commands

• stamp context – Generate context without style metadata
• stamp context --watch – Watch mode for automatic regeneration
• stamp context validate – Validate generated context files
• stamp context compare – Compare context files including style changes