Skip to content

AGENTS.md

Latest commit

 

History

History
102 lines (79 loc) · 6.29 KB

AGENTS.md

File metadata and controls

102 lines (79 loc) · 6.29 KB

Contribution guide for Apps SDK UI

Apps SDK UI is a design system tailored for building apps in ChatGPT. Apps SDK UI provides styling foundations, CSS variable design tokens, and a library of well-crafted, accessible components.

  • Design tokens – defined across colors, typography, spacing, sizing, shadows, surfaces, and more.
  • Tailwind 4 – fully integrated and pre-configured with Apps SDK UI's design tokens.
  • Component library – high-quality components built on top of Radix for consistent accessibility patterns.
  • Utilities – helpful tools for handling core concepts like dark mode, responsiveness, and more across React and CSS.

Keep this goal and context in mind as you contribute code to the repository. This code is the foundation for many other projects, and changes should be robust, well-considered, and workable for many different contexts.

Repository overview

You should make changes only in the src/ folder:

  • components/ - React component implementations (e.g., Button, Chat, Tooltip)
  • hooks/ - Reusable React hooks (e.g., useAutoGrowTextarea, useBreakpoints)
  • lib/ - Utility functions (theme helpers, attachment helpers, etc.)
  • styles/ - Global CSS config, Tailwind setup, and design token definitions
  • **/*.stories.tsx - Storybook stories definition for a given component
  • **/*.mdx - Storybook documentation, often referring to sibling .stories.tsx file
  • types.ts - Shared TypeScript types
  • vite-env.d.ts - Vite type declarations

When adding new functionality or docs, place files in the appropriate src/* location.

Components

File Naming Conventions

  • Component: ComponentName.tsx
  • Styles: ComponentName.module.css
  • Tests: ComponentName.test.tsx
  • Storybook:
    • ComponentName.stories.tsx
    • ComponentName.mdx

Component library

Below is a quick reference of all provided components:

Component Description
Alert Call attention to a specific message or warning.
Animate Animate components as they mount and unmount.
AnimateLayout Animate width & height of components as they mount and unmount.
AnimateLayoutGroup Animate width & height of lists of components as they enter and exit.
Avatar Display user identities with either text, photo, or an icon.
AvatarGroup Display avatars as a single stack.
Badge Emphasize details with a status indicator.
Button Create actions in many different styles.
ButtonLink <Button> but as a semantic anchor element.
Checkbox Toggle control for on and off states.
CodeBlock Display syntax‑highlighted code snippets.
CopyTooltip Allow users to easily copy to clipboard.
EmptyMessage Gracefully inform users when there's nothing to see.
Icon Collection of SVG icons exported as React components.
Image Load remote images with optional aspect ratio and cover mode.
Indicator Loading dots and circular progress indicators.
Input Semantic input text collection.
Markdown Render rich formatted content.
Menu Structured actions in a dropdown list.
Modal Capture focus for essential tasks or details.
AppsSDKUIProvider React provider for shared context (e.g., link component).
Popover Generic floating UI utility for contextual actions.
RadioGroup Radio button group selection component.
SegmentedControl Toggle through grouped options.
Select Choose from a dropdown of options.
SelectControl Alternative select control component with enhanced features.
Slider Fine-tune values within a set range.
Switch Toggle control for on and off states.
TagInput Enter multiple unique tags.
TextLink Semantic link used for both internal and external links.
Textarea Autosizable text input area with optional validation.
Tooltip Brief and informative hover text.
TransitionGroup Primitive for rendering components over time.

Documentation & Storybook

All components should be thoroughly documented in Storybook, using the .mdx and .stories sidecar files.

  • You should not need to run Storybook locally, so ignore the pnpm run storybook command
  • Update or create .mdx and .stories.tsx files when adding new components or features.
  • Keep usage examples simple and focused. Refer to documentation examples like Avatar, Badge, and Button for guidance.

Contributing

When working on features or documentation, avoid making unrelated changes to the current task. Do not add comments for obvious behaviors, and do not change build settings.

Setup instructions

  • Use Node version specified in .node-version
  • Install dependencies with npm install

Required commands before commit

  1. npm run format:fix - Auto-fixes any formatting issues
  2. npm run lint - Runs ESLint (TS) and Stylelint (CSS)
  3. npm run types - Runs TypeScript type checking
  4. npm run test - Executes unit tests via Vitest

Ignore all other script commands, as they will be irrelevant to your work.