@your-scope/atoms

Reusable, stateless atomic UI components for your design system, powered by now-design tokens and styles.

🚀 Installation

npm install @your-scope/atoms now-design-tokens now-design-styles
# or
yarn add @your-scope/atoms now-design-tokens now-design-styles

Note: now-design-tokens and now-design-styles are required peer dependencies. You must install them alongside this package.

🛠️ Usage

1. Import the tokens and styles CSS at your app entry point:

   import 'now-design-tokens/dist/css/variables.css';
   import 'now-design-styles/text/text-styles.css';

2. Import and use atoms in your components:

   import { IconAtom, TypographyAtom } from '@your-scope/atoms';
   
   <TypographyAtom className="bold-h5">Heading 5 Bold</TypographyAtom>
   <IconAtom icon={SomeIcon} color="icon-primary" size="icon-md" ariaLabel="Add" />

🎨 Logo Components

The package includes company logos with configurable theme-dependent text colors:

Brand Logos (Multi-Color with Configurable Text)

import { 
  LogoNowPurchase, 
  LogoMetalCloud, 
  LogoNowPurchaseMetalCloudCombined 
} from 'now-design-atoms';

// Basic usage - uses default CSS variable (--glass-surface-disabled)
<LogoNowPurchase width="200" />
<LogoMetalCloud width="200" />
<LogoNowPurchaseMetalCloudCombined width="400" />

// With custom CSS variable passed as prop
<LogoNowPurchase 
  width="200" 
  textColorVariable="--my-custom-text-color" 
/>

// Using your design system tokens
<LogoMetalCloud 
  width="200" 
  textColorVariable="--normal-typography-bodyPrimary" 
/>

Theme-Dependent Icons (Monochrome)

import { IconNowPurchase, IconMetalCloud } from 'now-design-atoms';

<IconNowPurchase color="var(--normal-typography-bodyPrimary)" width="100" />
<IconMetalCloud color="var(--normal-typography-bodyPrimary)" width="100" />

CSS Variable Setup

/* Light theme */
:root {
  --glass-surface-disabled: #1A1A1A;
  --my-custom-text-color: #2C2C2C;
  --normal-typography-bodyPrimary: #333333;
}

/* Dark theme */
[data-theme="dark"] {
  --glass-surface-disabled: #FFFFFF;
  --my-custom-text-color: #E0E0E0;
  --normal-typography-bodyPrimary: #FFFFFF;
}

Note: Brand logos preserve their original multi-color fills while making text elements configurable via the textColorVariable prop. You can pass any CSS variable name from your parent components.

🎨 Token-Driven Styling

• All visual properties (color, size, spacing, etc.) use tokens from now-design-tokens and styles from now-design-styles.
• Never use raw values (e.g., #fff, 16px) in your code—always use tokens and classes (e.g., color="icon-primary", className="bold-h5").

♿ Accessibility

• All atoms are stateless and accessible by default.
• Use ariaLabel, role, and tabIndex props as needed for screen readers and keyboard navigation.
• See Storybook for accessibility best practices and examples.

📚 Storybook & Documentation

• Every atom has a Storybook story showing all props, states, and variants.
• Usage examples always use tokens and classes, not raw values.
• Accessibility notes and best practices are included in stories.

🧩 Best Practices

• Atoms are stateless: all state is managed by parent components.
• Use only tokens and allowed classes for all styling.
• Import the tokens and styles CSS once at the app entry point.
• Keep your code DRY and composable.

🔗 Related Packages

• now-design-tokens: Design tokens for color, size, spacing, etc.
• now-design-styles: Prebuilt CSS classes for typography and more.
• @your-scope/icons: Icon library for use with IconAtom.

📝 License

MIT

🚀 Usage in UI (Not Storybook)

To use atoms in your application, import them directly from the package and ensure global styles are loaded:

// Import global styles (at your app entry point)
import 'now-design-styles/text/text-styles.css';
import 'now-design-styles/fonts/fonts.css';

// Import atoms
import { AccordionTrigger, SelectableListItem, Typography, Icon } from '@your-scope/atoms';

function Example() {
  return (
    <div>
      <AccordionTrigger
        label="Section Title"
        expanded={false}
        onToggle={() => {}}
        icon="SystemAddFill"
      />
      <SelectableListItem
        icon="User"
        label="Profile"
        selected={true}
        onSelect={() => {}}
      />
      <Typography className="bold-h4">Heading</Typography>
      <Icon icon="SystemAddFill" />
    </div>
  );
}

Note: Always import the global styles from now-design-styles at your app's entry point to ensure all tokens and typography are applied correctly.