Component Spec vs Brand.yml

Component Spec

By JR Brugger (Design Workflow)

Write complete design system specs covering variants, states, accessibility, and usage.

Brand.yml

By Posit

Define your brand colors, fonts, and logos once, use them everywhere in Shiny and Quarto.

Component Spec

• Generates structured component specifications with anatomy breakdowns, variants, and props
• Documents all component states (hover, focus, disabled, loading, error) with clear descriptions
• Includes accessibility requirements like ARIA roles, keyboard navigation, and screen reader support
• Provides usage guidelines with do/don't examples and content rules
• Covers behavior details like interactions, animations, and responsive breakpoints

Brand.yml

• Creates a single YAML file that stores your brand colors, fonts, and logo files
• Automatically applies your branding to Shiny web apps and Quarto documents
• Supports light and dark mode variants for colors and logos
• Integrates with Google Fonts and custom typography
• Works across HTML reports, dashboards, slides, and PDFs

Reach for Component Spec when…

• You're building a design system and need to document components thoroughly
• Your team needs shared specs so designers and developers stay aligned
• You're onboarding someone and want clear component documentation to reference
• You need to ensure accessibility is baked into every component from the start

Reach for Brand.yml when…

• You're setting up brand guidelines for a team's reports and dashboards
• You need consistent colors and fonts across multiple documents without manual styling
• You're creating Shiny apps or Quarto reports and want them to match your brand
• You want to update your brand palette once and have it apply everywhere