Principles

Sugarcube components are copy-to-use components that you can alter as needed. They’re designed to work seamlessly with the kind of ‘token-driven development’ that sugarcube encourages.

Framework Flexibility

Components are available in multiple forms:

  • React (tsx)
  • Astro (native) - coming soon
  • Astro (enhanced) - coming soon
  • Web Components - coming soon

This ensures you can use sugarcube in any project, regardless of framework, and use the right amount of JavaScript for your needs.

API Freedom

Sugarcube doesn’t prescribe any component API. You’re free to implement things like variants as you prefer:

// JavaScript approach
<Button variant="secondary">Primary</Button>


// CSS approach
<Button data-variant="secondary">Primary</Button>

For React components, we use Radix UI as a foundation for complex components like Accordion or Dialog. This means those React components inherit Radix’s API for accessibility and behavior.

Astro and Web Component versions are built from scratch with no API constraints.

CSS-First Design

Sugarcube components are designed to work seamlessly with CSS methodologies like CUBE CSS, but we don’t prescribe how you handle variants and state changes. You can choose the approach that fits your project:

// JavaScript/props approach
<AvatarGroup overlap animated filtered>
  <Avatar size="lg" variant="square">...</Avatar>
</AvatarGroup>


// CSS/data attributes approach
<div className="avatar-group" data-overlap data-animated data-filtered>
  <Avatar data-size="lg" data-variant="square">...</Avatar>
</div>

Both approaches have their merits:

  • Props approach: Type safety, better IDE support, more React-like
  • Data attributes approach: Keeps styling in CSS, reduces JavaScript overhead, more framework-agnostic, aligns with CUBE CSS principles

Sugarcube gives you the flexibility to choose what works best for your team and project structure.

Composition

Components favor composition over complex prop APIs:

<Card>
    <Card.Title>Card Title</Card.Title>
    <Card.Content>Card Content</Card.Content>
    <Card.Footer>Card Footer</Card.Footer>
</Card>

This pattern provides flexibility, reduces cognitive load, and makes the structure more intuitive.

<Card>
    <Card.Title>Card Title</Card.Title>
    <Card.Content>Card Content</Card.Content>
    <Card.Footer>Card Footer</Card.Footer>
</Card>