Core Components

Core Components

What Is This?

The "Core Components" skill for the Happycapy Skills platform defines the foundational practices and patterns for building user interfaces using a shared component library and a unified set of design tokens. It serves as both a reference and a rulebook for implementing UI elements in a way that ensures visual and behavioral consistency across products. This skill covers the use of design tokens for spacing, color, and typography, as well as guidelines for leveraging core UI components rather than using raw platform primitives.

By using the standards outlined in this skill, teams can avoid design drift, reduce technical debt, and maintain a scalable, maintainable codebase. The skill also reinforces the importance of semantic tokens over hard-coded values, providing a clear mapping between tokens and their intended purposes.

Why Use It?

Consistent user interfaces are essential for building trust and delivering a cohesive brand experience. Without a shared design system and component library, applications can quickly become fragmented, with inconsistent spacing, colors, fonts, and behaviors. The "Core Components" skill addresses these issues by:

• Enforcing consistency: Using core components and design tokens prevents small but impactful inconsistencies.
• Supporting scalability: As your application grows, a shared component library makes it easier to introduce new features without reinventing foundational UI elements.
• Improving maintainability: When updates are made to the design system (such as changing a color or spacing scale), those changes propagate automatically through all components using tokens.
• Reducing cognitive load: Developers and designers can focus on application logic and experience rather than low-level styling decisions.
• Enhancing accessibility: Core components often come with built-in accessibility features, reducing the risk of accessibility regressions.

How to Use It

Use Core Components, Not Raw Primitives

When constructing UI, always use components from the core library (for example, Box, Text, and other shared building blocks) instead of raw platform elements like <div> or <span>. Core components encapsulate styling, behavior, and accessibility patterns that would otherwise need to be reimplemented for each new element.

Always Use Design Tokens

Never hard-code style values. Design tokens are named variables for spacing, colors, and typography. They create a single source of truth for your UI's visual language.

Spacing Tokens

Use spacing tokens for padding and margin. For example:

// Correct usage with tokens
<Box padding="$4" marginBottom="$2" />

// Incorrect: hard-coded values
<Box padding={16} marginBottom={8} />

The available spacing tokens map to pixel values as follows:

Color Tokens

Instead of direct color definitions, use semantic color tokens:

// Correct: semantic tokens
<Text color="$textPrimary" />
<Box backgroundColor="$backgroundSecondary" />

// Incorrect: hard-coded colors
<Text color="#333333" />
<Box backgroundColor="rgb(245, 245, 245)" />

Semantic tokens provide meaning and adaptability. For example:

Typography Tokens

Typography tokens standardize font sizes and weights:

<Text fontSize="$lg" fontWeight="$semibold" />

Available size tokens:

Example:

Building a Card Component

<Box padding="$6" backgroundColor="$backgroundSecondary" borderRadius="$3">
  <Text fontSize="$lg" fontWeight="$semibold" color="$textPrimary">
    Card Title
  </Text>
  <Text fontSize="$md" color="$textSecondary" marginTop="$2">
    Card body text goes here. Consistent spacing and colors are ensured by design tokens.
  </Text>
</Box>

This example demonstrates how spacing, color, and typography tokens, together with core components, yield a visually consistent and maintainable UI element.

When to Use It

• When building any new UI: All new interface elements must use core components and design tokens as described in this skill.
• When refactoring or updating legacy code: Migrate old code to use the shared component library and replace hard-coded values with tokens.
• When collaborating on design and implementation: Use this skill as a reference for both design handoff and code review to ensure alignment across disciplines.

Important Notes

• Never use hard-coded values for spacing, color, or typography. This undermines the consistency and maintainability of your UI.
• Always prefer semantic tokens over raw values. This enables theming and future design changes with minimal refactoring.
• Do not use raw HTML or platform primitives unless absolutely necessary. Core components are purpose-built to encapsulate best practices.
• Review the design system documentation regularly for updates to tokens or component patterns.
• Consult the core component library source (source code) for the most up-to-date implementation details.

By following the guidance in this skill, teams can deliver robust, scalable, and visually unified applications while minimizing technical debt and rework.