react-component-library-usage

jakewaldrip's avatarfrom jakewaldrip

Guidelines for using the Commonplace Design System in React components

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026
[Code Generation]

When & Why to Use This Skill

This Claude skill provides comprehensive guidelines and best practices for implementing the Commonplace Design System within React components. It ensures frontend consistency, accessibility, and maintainability by offering clear instructions on component usage, slot-based layouts, and customization priorities. By integrating these rules, developers can generate high-quality UI code that adheres to organizational standards while minimizing custom CSS and technical debt.

Use Cases

  • Standardized UI Development: Generate React components that strictly follow the Commonplace Design System's architecture and accessibility standards.
  • Legacy Code Modernization: Transform legacy HTML and custom CSS into clean, reusable components from the Commonplace library.
  • Design System Compliance: Enforce the 'Props → Slots → className' hierarchy to maintain a consistent look and feel across the application.
  • Themed Styling Implementation: Correctly implement custom styles using approved CSS variables for colors and typography to ensure design system integrity.
namereact-component-library-usage
descriptionGuidelines for using the Commonplace Design System in React components

Overview

This project uses the Commonplace Design System, Cityblock's comprehensive library of consistent, accessible, and well-tested components.

  • Located at: commons-packages/commonplace/
  • Import from: @cityblock/commonplace
  • Documentation: https://commonplace.design
  • Before building anything new, check commonplace.ts and associated .stories.tsx files

Usage Examples

// Good - Using Commonplace components with slots
import { Card, VerticalStack, Text, Row, Tag, Button } from '$commons/app/shared/commonplace';

<Card
  title="Patient information"
  actions={<Button text="Edit" />}
  leftContent={<Tag text="Active" />}
  titleRowContent={<Tag text="High priority" />}
>
  <VerticalStack gap="medium">
    <Text element="p" text="Patient details content" />
    <Text element="p" text="Event description" />
  </VerticalStack>
</Card>

// Avoid - Custom styling, custom classes
<div style={{ padding: '16px', backgroundColor: '#f5f5f5' }}>
  <h2 style={{ fontSize: '18px' }}>Title</h2>
  <p class="mt-6">Content</p>
</div>

Guidelines

  • Use Commonplace components over raw HTML or custom elements
  • Customization priority: Props → Slots → className → Wrappers → Never direct CSS
  • Don't edit component source - customize through usage only
  • When components don't exist: Search thoroughly, try composition, then propose new component

Custom CSS

Only add custom CSS if the Commonplace component doesn't provide a prop to achieve the desired styling. Use existing CSS variables instead of custom px, em, rem, or hex values. For example:

// component.tsx
import { Text } from '$commons/app/shared/commonplace';
import styles from './css/component.css'

<Text element="p" text="Item details" className={styles.details} />

// component.css
.details {
  color: var(--color-text-light);
  font-size: var(--font-size-body-sm);
  line-height: var(--line-height-body-sm);
}