Quick Start Guide

This guide will help you configure the ThemeProvider and start using Natura Design System components in your React application.

Step 1: Set Up ThemeProvider

The ThemeProvider is essential for the design system to work correctly. It provides theme context to all components and ensures styles are applied properly.

Basic Setup

Wrap your application with ThemeProvider at the root level:

App.tsx

import React from 'react'
import { ThemeProvider, buildTheme, Button } from '@naturacosmeticos/natds-react'

// Build a theme for your brand
const theme = buildTheme('natura', 'light')

function App() {
  return (
    <ThemeProvider theme={theme} cssPrefix="my-app">
      <div className="App">
        <h1>Welcome to Natura Design System</h1>
        <Button variant="contained" onClick={() => alert('Hello!')}>    
          Click Me
        </Button>
      </div>
    </ThemeProvider>
  )
}

export default App

The cssPrefix prop is required to avoid style conflicts with multiple instances of the design system or other CSS frameworks.

Step 2: Understanding buildTheme

The buildTheme function creates a theme configuration based on brand and color mode.

Function Signature

buildTheme(brand: Brand, mode: ThemeMode): Theme

Parameters

brand

string

required

The brand name for theming. Available options:

'natura' - Natura Cosméticos (default)
'avon' - Avon
'theBodyShop' - The Body Shop
'aesop' - Aesop

mode

string

required

The color scheme mode. Available options:

'light' - Light mode (default)
'dark' - Dark mode

Theme Examples

import { buildTheme } from '@naturacosmeticos/natds-react'

const theme = buildTheme('natura', 'light')

Do not try to override theme palette or tokens directly. The design system themes are production-ready and modifications may cause inconsistencies.

Step 3: Using Components

Once ThemeProvider is configured, you can use any component from the design system.

Button Component

The Button component supports multiple variants, sizes, and can include icons:

ButtonExample.tsx

import React from 'react'
import { Button } from '@naturacosmeticos/natds-react'

function ButtonExample() {
  return (
    <div style={{ display: 'flex', gap: '16px' }}>
      {/* Contained Button (default) */}
      <Button 
        variant="contained" 
        onClick={() => console.log('Contained clicked')}
      >
        Contained
      </Button>

      {/* Outlined Button */}
      <Button 
        variant="outlined" 
        onClick={() => console.log('Outlined clicked')}
      >
        Outlined
      </Button>

      {/* Text Button */}
      <Button 
        variant="text" 
        onClick={() => console.log('Text clicked')}
      >
        Text Button
      </Button>

      {/* Button with Icon */}
      <Button
        variant="contained"
        showIcon
        iconName="outlined-action-add"
        iconPosition="right"
        onClick={() => console.log('Icon button clicked')}
      >
        Add Item
      </Button>

      {/* Full Width Button */}
      <Button
        variant="contained"
        fullWidth
        onClick={() => console.log('Full width clicked')}
      >
        Full Width
      </Button>
    </div>
  )
}

export default ButtonExample

Button Props Reference

variant

'contained' | 'outlined' | 'text'

default:"contained"

The visual style of the button

size

'semi' | 'semiX' | 'medium'

default:"semiX"

The size of the button

color

ButtonColor

default:"primary"

The color scheme: 'primary', 'secondary', 'onPrimary', 'onSecondary', 'surfaceInverse', 'onSurfaceInverse'

disabled

boolean

default:false

Whether the button is disabled

fullWidth

boolean

default:false

If true, the button occupies 100% width

showIcon

boolean

If true, displays an icon alongside the text

iconName

IconName

The icon to display (required when showIcon is true). See Icon Library

iconPosition

'left' | 'right'

default:"right"

Position of the icon relative to text

Card Component

The Card component provides a container with elevation and rounded corners:

CardExample.tsx

import React from 'react'
import { Card, Typography } from '@naturacosmeticos/natds-react'

function CardExample() {
  return (
    <div style={{ padding: '24px', display: 'grid', gap: '16px' }}>
      {/* Card with elevation and radius (default) */}
      <Card>
        <div style={{ padding: '16px' }}>
          <h3>Product Card</h3>
          <p>This card has elevation and rounded corners by default.</p>
        </div>
      </Card>

      {/* Card without elevation */}
      <Card elevation={false}>
        <div style={{ padding: '16px' }}>
          <h3>Flat Card</h3>
          <p>This card has no elevation (shadow).</p>
        </div>
      </Card>

      {/* Card without radius */}
      <Card radius={false}>
        <div style={{ padding: '16px' }}>
          <h3>Square Card</h3>
          <p>This card has no border radius.</p>
        </div>
      </Card>
    </div>
  )
}

export default CardExample

Card Props Reference

elevation

boolean

default:true

If true, applies shadow elevation to the card

radius

boolean

default:true

If true, applies border radius to the card

Step 4: Complete App Example

Here’s a complete example that combines multiple components:

App.tsx

import React, { useState } from 'react'
import {
  ThemeProvider,
  buildTheme,
  Button,
  Card,
  TextField,
  Switch,
} from '@naturacosmeticos/natds-react'

function App() {
  const [isDark, setIsDark] = useState(false)
  const [name, setName] = useState('')
  
  // Rebuild theme when mode changes
  const theme = buildTheme('natura', isDark ? 'dark' : 'light')

  const handleSubmit = () => {
    alert(`Hello, ${name}!`)
  }

  return (
    <ThemeProvider theme={theme} cssPrefix="my-app">
      <div style={{ 
        padding: '32px',
        minHeight: '100vh',
        backgroundColor: isDark ? '#1a1a1a' : '#f5f5f5'
      }}>
        {/* Theme Switcher */}
        <div style={{ marginBottom: '24px' }}>
          <label style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
            <span>Dark Mode</span>
            <Switch 
              checked={isDark} 
              onChange={(e) => setIsDark(e.target.checked)}
            />
          </label>
        </div>

        {/* Main Content */}
        <Card>
          <div style={{ padding: '24px' }}>
            <h1>Welcome to Natura Design System</h1>
            <p>Start building beautiful interfaces with production-ready components.</p>
            
            <div style={{ marginTop: '24px', marginBottom: '16px' }}>
              <TextField
                label="Your Name"
                value={name}
                onChange={(e) => setName(e.target.value)}
                placeholder="Enter your name"
              />
            </div>

            <div style={{ display: 'flex', gap: '12px' }}>
              <Button 
                variant="contained" 
                onClick={handleSubmit}
                disabled={!name}
              >
                Submit
              </Button>
              
              <Button 
                variant="outlined" 
                onClick={() => setName('')}
              >
                Clear
              </Button>
            </div>
          </div>
        </Card>
      </div>
    </ThemeProvider>
  )
}

export default App

Available Components

The design system includes 40+ production-ready components:

Buttons

Button, IconButton, GayaButton

Forms

TextField, Input, Select, Checkbox, RadioButton, Switch

Layout

Card, Divider, Drawer, Dialog

Navigation

AppBarTop, Tab, TabItem, Link, MenuItem

Feedback

Alert, Snackbar, ProgressIndicator, Badge

Data Display

Typography, Avatar, Chip, Tag, Label, Image, Icon, Logo, Rating

Disclosure

AccordionGroup, AccordionItem, Collapse

Lists

ListItem, Autocomplete

Other

Counter, Shortcut, Portal, Ripple

Using TypeScript

The design system includes full TypeScript support. All components export their prop types:

TypeScriptExample.tsx

import React from 'react'
import { Button, ButtonProps } from '@naturacosmeticos/natds-react'

// Component props are fully typed
const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />
}

// Or use inline types
function Example() {
  const handleClick: ButtonProps['onClick'] = () => {
    console.log('Typed click handler')
  }
  
  return (
    <Button variant="contained" onClick={handleClick}>
      Typed Button
    </Button>
  )
}

Accessing Theme Values

You can access theme values using the useTheme hook from react-jss:

ThemeAccess.tsx

import React from 'react'
import { useTheme } from '@naturacosmeticos/natds-react'
import { Theme } from '@naturacosmeticos/natds-themes'

function ThemeExample() {
  const theme = useTheme<Theme>()
  
  return (
    <div style={{
      padding: theme.spacing.standard,
      backgroundColor: theme.color.primary,
      color: theme.color.onPrimary,
      borderRadius: theme.border.radius.medium
    }}>
      Using theme values directly
    </div>
  )
}

export default ThemeExample

Next Steps

Explore Components

Check out the Storybook for interactive examples of all components

Review Design Guidelines

Visit Zero Height for design specifications and usage guidelines

Browse Icon Library

Explore 1000+ available icons for use with components

Join the Community

Contribute or report issues on GitHub

Tips & Best Practices

Always use ThemeProvider at the root of your app. Components will not render correctly without it.

Use the cssPrefix prop to avoid CSS class name conflicts, especially in micro-frontend architectures.

Don’t override theme values. The design system themes are production-ready and modifications may break the design consistency.

Icon names must match exactly from the icon library. Check the Icon Library documentation for available names.

Troubleshooting

If components aren’t rendering correctly:

Verify ThemeProvider is wrapping your app
Check that all required fonts are loaded in your HTML
Ensure React version >= 16.8.4
Verify icon CSS is loaded if using Icon components
Add a unique cssPrefix to avoid style conflicts

For more help, see the Troubleshooting Guide.

Get Started

Packages

Theming

Guides

Quick Start

Quick Start Guide

Step 1: Set Up ThemeProvider

Basic Setup

Step 2: Understanding buildTheme

Function Signature

Parameters

Theme Examples

Step 3: Using Components

Button Component

Button Props Reference

Card Component

Card Props Reference

Step 4: Complete App Example

Available Components

Buttons

Forms

Layout

Navigation

Feedback

Data Display

Disclosure

Lists

Other

Using TypeScript

Accessing Theme Values

Next Steps

Tips & Best Practices

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Packages

Theming

Guides

​Quick Start Guide

​Step 1: Set Up ThemeProvider

​Basic Setup

​Step 2: Understanding buildTheme

​Function Signature

​Parameters

​Theme Examples

​Step 3: Using Components

​Button Component

​Button Props Reference

​Card Component

​Card Props Reference

​Step 4: Complete App Example

​Available Components

Buttons

Forms

Layout

Navigation

Feedback

Data Display

Disclosure

Lists

Other

​Using TypeScript

​Accessing Theme Values

​Next Steps

​Tips & Best Practices

​Troubleshooting

Build docs developers (and LLMs) love

Quick Start Guide

Step 1: Set Up ThemeProvider

Basic Setup

Step 2: Understanding buildTheme

Function Signature

Parameters

Theme Examples

Step 3: Using Components

Button Component

Button Props Reference

Card Component

Card Props Reference

Step 4: Complete App Example

Available Components

Using TypeScript

Accessing Theme Values

Next Steps

Tips & Best Practices

Troubleshooting