Skip to content

feat: Initial import of Simple Design System #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
akhdefault wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Initial import of Simple Design System #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
164 changes: 15 additions & 149 deletions .cursor/rules/usage-guidelines.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ SDS is a production-ready design system featuring:
- 🎨 **Figma Integration**: Full Code Connect integration with variables, styles, and components
- ⚛️ **React Components**: Built on React Aria/Stately for accessibility
- 🎯 **TypeScript**: Fully typed component library
- 📚 **Storybook**: Comprehensive component documentation

- 🎨 **Design Tokens**: CSS custom properties with light/dark mode support
- 📱 **Responsive**: Mobile-first responsive design patterns

Expand All @@ -18,15 +18,14 @@ SDS is a production-ready design system featuring:
### Development Commands

- `npm run app:dev` - Start development server at localhost:8000
- `npm run storybook` - Launch Storybook at localhost:6006

- `npm run app:build` - Build the application
- `npm run storybook:build` - Build Storybook

- `npm run script:tokens` - Sync design tokens from Figma
- `npm run script:icons` - Sync icons from Figma

### Key Resources

- [Live Storybook](https://figma.github.io/sds/storybook) - Component documentation
- [Figma Community File](https://www.figma.com/community/file/1380235722331273046/simple-design-system) - Design source

## Quick Start Checklist
Expand All @@ -38,7 +37,7 @@ Before implementing any Figma design, follow this checklist:
- When trying to get a high level understanding of the design, you can use #get_image to get image representation of the design to contextualize what is selected in Figma
- Whenever you want more information about the specific UI elements that are selected, use #get_code
- With the get_code, get_code_connect_map, and get_variable_map tools you will receive information about patterns that should already be defined in this repository.
- If patterns dont already exist, you should ask for permission and clarify what about the design isn't already accounted for in this codebase that is present in the design.
- If patterns dont already exist, you should ask for permission and clarify what about the design't already accounted for in this codebase that is present in the design.

2. ✅ **Read component APIs** in the actual TypeScript files before using
3. ✅ **Use SDS components only** - never import from `@react-aria`, `@react-stately`, etc.
Expand All @@ -50,27 +49,16 @@ Before implementing any Figma design, follow this checklist:
When importing SDS components, use aliases to ensure correct paths. These are described in the `vite.config.ts` file under `resolve.alias`:

```tsx
import { Footer, Header } from "compositions";
import {
useAuth,
usePricing,
useProducts,
AuthProvider,
PricingProvider,
ProductsProvider,
AllProviders,
} from "data";
import { useMediaQuery } from "hooks";
import { useMediaQuery } from "utils";
import { IconChevronLeft } from "icons";
import { placeholder } from "images";
import { Flex, Section } from "layout";
import {
Accordion,
AccordionItem,
Button,
TextContentHeading,
TextContentTitle,
} from "primitives";
} from "components";
```

## Figma to SDS Translation Guidelines
Expand Down Expand Up @@ -120,48 +108,26 @@ All design tokens from Figma are defined as CSS variables in [src/theme.css](../

```
src/
├── data/ # Data layer - contexts, providers, services, types
│ ├── contexts/ # React context definitions (AuthContext, PricingContext, ProductsContext)
│ ├── providers/ # Context providers with state management
│ ├── services/ # API and business logic services
│ ├── types/ # TypeScript type definitions for data models
│ └── hooks/ # Data-specific custom hooks (useAuth, usePricing, useProducts)
├── ui/ # UI component library
│ ├── primitives/ # Atomic components (Button, Input, etc.)
│ ├── compositions/ # Complex components (Cards, Forms, etc.)
│ ├── layout/ # Layout components (Flex, Section, Grid)
│ ├── components/ # Atomic components (Button, Input, etc.)
│ ├── hooks/ # UI-specific custom hooks (useMediaQuery)
│ ├── icons/ # SVG icon components
│ ├── images/ # Image assets
│ └── utils/ # Utility functions and components
├── stories/ # Storybook stories for all components
├── examples/ # Examples of how to use components together in larger complete sections

├── figma/ # Figma [Code Connect](https://www.figma.com/code-connect-docs/react/) files
│ ├── primitives/ # Maps Figma components to React primitives
│ ├── compositions/ # Maps Figma compositions to React components
│ ├── components/ # Maps Figma components to React components
│ └── icons/ # Maps Figma icons to React icons
├── theme.css # CSS custom properties (design tokens)
├── reset.css # CSS reset
├── responsive.css # Responsive utilities
└── App.tsx # Demo application
```

### Scripts Directory

```
scripts/
├── tokens/ # Design token sync from Figma
├── icons/ # Icon sync from Figma
├── component-metadata/ # Component metadata management
└── dev-resources/ # Development resource generation
```

## Component Library Structure

All UI components are in [src/ui](../src/ui). **Never create new components - always use existing SDS components.**

All data management (contexts, providers, services, types, and data hooks) are in [src/data](../src/data). Use the provided context providers and custom hooks for state management.

## SDS Component Hierarchy

When you see `hidden={true}` in Figma data, it indicates that the node should be ignored. This can happen with Figma components frequently, as nodes that can be toggled with a prop need to exist, even when the prop is false.
Expand All @@ -171,11 +137,11 @@ When you see `hidden={true}` in Figma data, it indicates that the node should be
## Figma Translation Process

1. **Extract design using Figma tools**: Always use the Figma MCP tools to get the design data
2. **Identify SDS components**: Map Figma components to existing SDS primitives, compositions, and layouts
2. **Identify SDS components**: Map Figma components to existing SDS components, and layouts
- Use the `codeDependencies` field to find the correct component path
- If no direct mapping exists, look for similar components or compositions
- If no direct mapping exists, look for similar components
3. **Check component APIs**: Read the actual component files to understand props and usage patterns
4. **Use semantic imports**: Import from correct paths (e.g., `import { Button } from "ui/primitives/Button/Button"`)
4. **Use semantic imports**: Import from correct paths (e.g., `import { Button } from "ui/components/Button/Button"`)
5. **Apply design tokens**: Use CSS variables for all styling values

## Common Translation Patterns
Expand All @@ -201,68 +167,13 @@ When you see `hidden={true}` in Figma data, it indicates that the node should be
</Navigation>
```

### Typography

```tsx
// Figma: Text with specific styles
// SDS Implementation:
<TextHeading>Heading Text</TextHeading>
<Text>Body text</Text>
<TextSmall>Small text</TextSmall>
```

### Layout

```tsx
// Figma: Cards in a grid
// SDS Implementation:
<Section>
<Flex direction="row" gap="400" type="third">
<div>Card 1</div>
<div>Card 2</div>
<div>Card 3</div>
</Flex>
</Section>
```

```tsx
// Complex layout with responsive behavior
function ResponsiveExample() {
const { isMobile } = useMediaQuery();

return (
<Section variant="stroke" padding={isMobile ? "600" : "1600"}>
<Flex
direction="column"
container
gap={isMobile ? "600" : "1200"}
alignPrimary="center"
>
{/* Navigation Pills */}
<Navigation direction="row">
<NavigationPill isSelected>Active</NavigationPill>
<NavigationPill>Inactive</NavigationPill>
</Navigation>

{/* Content Grid */}
<Flex direction={isMobile ? "column" : "row"} gap="1600" type="third">
{content.map((item) => (
<Card key={item.id} {...item} />
))}
</Flex>
</Flex>
</Section>
);
}
```

## Best Practices & Common Pitfalls

### Component API Guidelines

- **Always check existing component props**: Read the TypeScript definitions in component files
- **Use semantic prop names**: `isSelected` not `active`, `variant` not `type`
- **Leverage composition**: Combine primitives rather than creating custom components
- **Leverage composition**: Combine components rather than creating custom components
- **Follow naming conventions**: PascalCase for components, camelCase for props

### Essential Rules
Expand Down Expand Up @@ -301,7 +212,7 @@ function ResponsiveExample() {

## Component Categories

### Primitives (`src/ui/primitives/`)
### components (`src/ui/components/`)

Single-purpose, reusable components (alphabetically ordered):

Expand Down Expand Up @@ -334,57 +245,12 @@ Single-purpose, reusable components (alphabetically ordered):
- **Textarea** - Multi-line text input with resize options
- **Tooltip** - Contextual help and information overlays

### Layout (`src/ui/layout/`)

Structural components for positioning:

- **Flex** - Flexbox layouts with gap, alignment, and responsive props
- **Section** - Page sections with padding and background variants
- **Grid** - CSS Grid layouts (when Flex isn't sufficient)

### Compositions (`src/ui/compositions/`)

Complex, pre-built component patterns:

- **Cards** - Content cards with headers, bodies, and actions
- **Forms** - Complete form layouts with validation. Meant to be examples.
- **Headers/Footers** - Page navigation and footer components

### Hooks (`src/ui/hooks/`)

UI-specific custom React hooks:

- **useMediaQuery** - Responsive breakpoint detection

### Data Layer (`src/data/`)

Data management layer with contexts, providers, services, and hooks:

#### Hooks (`src/data/hooks/`)

- **useAuth** - Authentication state and methods (login, logout, user data)
- **usePricing** - Pricing plans, cart management, and billing operations
- **useProducts** - Product catalog, search, filtering, and shopping cart

#### Providers (`src/data/providers/`)

- **AuthProvider** - Authentication context with loading states and error handling
- **PricingProvider** - Pricing and subscription management
- **ProductsProvider** - Product catalog and e-commerce functionality
- **AllProviders** - Combined provider wrapper for full application state

#### Services (`src/data/services/`)

- **authService** - Authentication API calls and token management
- **pricingService** - Pricing calculations and plan management
- **productsService** - Product data, filtering, and search operations

#### Types (`src/data/types/`)

- **auth.ts** - User, credentials, and authentication types
- **pricing.ts** - Plans, pricing, and cart types
- **products.ts** - Product, filter, and e-commerce types

## Figma Integration

SDS uses Figma Code Connect for seamless design-to-code integration. Here's how it works:
Expand All @@ -398,7 +264,7 @@ SDS uses Figma Code Connect for seamless design-to-code integration. Here's how
To enable Code Connect:

1. Use the **"SDS - Design Tokens"** and **"SDS - Components"** styles in Figma
2. Organize components in Figma using the same structure as SDS (primitives, compositions, etc.)
2. Organize components in Figma using the same structure as SDS (components, compositions, etc.)
3. Publish changes in Figma, then run `npm run script:tokens` and `npm run script:icons` to sync

### Known Limitations
Expand Down
2 changes: 0 additions & 2 deletions .env-rename
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion .eslintrc.cjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ module.exports = {
"eslint:recommended",
"plugin:@typescript-eslint/recommended",
"plugin:react-hooks/recommended",
"plugin:storybook/recommended",

],
ignorePatterns: ["dist", ".eslintrc.cjs"],
parser: "@typescript-eslint/parser",
Expand Down
Loading