@faststore/ui 4.1.0-dev.3 → 4.1.0-dev.5

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://faststore.dev">
+  <a href="https://developers.vtex.com/docs/guides/faststore">
     <img alt="Faststore" src="./static/logo.png" width="60" />
   </a>
 </p>
@@ -11,42 +11,87 @@
     Lightweight ecommerce component library
   </strong>
 </p>
-
-<div style="display: flex; justify-content: center; width: 100%">
-  <a href="https://www.npmjs.com/package/@faststore/ui" style="padding: 0px 2px 0px 0px">
-    <img src="https://badge.fury.io/js/%40faststore%2Fui.svg" />
-  </a>
-  <a href="https://bundlephobia.com/package/@faststore/ui" style="padding: 0px 2px 0px 2px">
-    <img src="https://badgen.net/bundlephobia/minzip/@faststore/ui" />
-  </a>
-  <a href="https://bundlephobia.com/package/@faststore/ui" style="padding: 0px 2px 0px 2px">
-    <img src="https://badgen.net/bundlephobia/tree-shaking/@faststore/ui" />
-  </a>
-  <a href="https://bundlephobia.com/package/@faststore/ui" style="padding: 0px 0px 0px 2px">
-    <img src="https://badgen.net/bundlephobia/dependency-count/@faststore/ui" />
+<p align="center">
+  <a href="https://www.npmjs.com/package/@faststore/ui">
+    <img src="https://badge.fury.io/js/%40faststore%2Fui.svg" alt="npm version" />
   </a>
-</div>
+</p>
+
+`@faststore/ui` is the styling layer for FastStore UI components. It re-exports all components from `@faststore/components` and adds two styling layers on top:
+
+- **Design tokens** — global CSS custom properties for colors, typography, spacing, borders, and shadows
+- **Structural styles** — minimum SCSS needed for components to function, using data attribute selectors
 
-## Installation
+Components in this package have no styles by default — all customization happens through the token system.
 
-From the command line in your project directory, run pnpm add `@faststore/ui`.
+## Package structure
 
-```cmd
-pnpm add @faststore/ui
+```text
+src/
+├── components/
+│   ├── atoms/       # SCSS per atom (e.g. Badge/styles.scss, Button/styles.scss)
+│   ├── molecules/   # SCSS per molecule
+│   └── organisms/   # SCSS per organism
+├── styles/
+│   ├── base/        # Global reset, tokens, typography, layout, utilities
+│   ├── components.scss  # Imports all component stylesheets
+│   └── global.scss      # Entry point for all styles
+├── typings/         # Shared TypeScript types
+└── index.ts         # Re-exports all components from @faststore/components
 ```
 
-## Usage
+## How to run
+
+### Prerequisites
+
+- Node.js ≥ 20
+- pnpm
 
-```tsx
-import React from 'react'
+### Local setup
 
-import { Button } from '@faststore/ui'
+```bash
+# 1. Install dependencies (from the repo root)
+pnpm install
 
-function MyComponent {
-  return <Button variant="primary">Add to Cart</Button>
-}
+# 2. Start the build in watch mode
+pnpm dev
 ```
 
-## Docs
+For interactive visual testing, use Storybook. Run `pnpm dev` from `packages/storybook/`.
+
+## How to develop
+
+### Adding styles for a new component
+
+1. Create `src/components/{category}/{ComponentName}/styles.scss`
+2. Use the component's root data attribute as the selector:
+   ```scss
+   [data-fs-badge] {
+     // 1. Define local tokens mapped to global tokens
+     --fs-badge-padding: var(--fs-spacing-2);
+     --fs-badge-text-color: var(--fs-color-text);
+
+     // 2. Apply structural styles using local tokens
+     color: var(--fs-badge-text-color);
+
+     // 3. Variant styles using state attributes
+     &[data-fs-badge-variant="success"] {
+       --fs-badge-text-color: var(--fs-color-success-text);
+     }
+   }
+   ```
+3. Register the stylesheet in `src/styles/components.scss`:
+   ```scss
+   @import "../components/atoms/Badge/styles";
+   ```
+
+> Always map local tokens to global tokens first — this ensures compatibility with theme customization. See [`AGENTS.md`](../../AGENTS.md#step-3-add-styling-faststoreui) for the full styling guidelines.
+
+## How to publish
+
+Versioning and publishing are managed at the monorepo root by Lerna. Do not publish this package independently. Refer to the [Contributing guidelines](../../CONTRIBUTING.MD) for the full release workflow.
+
+## Documentation
 
-For more information, please refer to our FastStore UI documentation:https://developers.vtex.com/docs/guides/faststore/components-index
+- **Component reference:** [developers.vtex.com/docs/guides/faststore/components-index](https://developers.vtex.com/docs/guides/faststore/components-index)
+- **Styling guidelines:** [`AGENTS.md`](../../AGENTS.md#step-3-add-styling-faststoreui)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faststore/ui",
-  "version": "4.1.0-dev.3",
+  "version": "4.1.0-dev.5",
   "description": "A lightweight, framework agnostic component library for React",
   "author": "emersonlaurentino",
   "license": "MIT",
@@ -47,7 +47,7 @@
     }
   ],
   "dependencies": {
-    "@faststore/components": "4.1.0-dev.3",
+    "@faststore/components": "4.1.0-dev.5",
     "include-media": "^2.0.0",
     "modern-normalize": "^1.1.0",
     "react-swipeable": "catalog:",
@@ -72,5 +72,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "83d08ea86efed01d93749e743f5c32172d41a5ab"
+  "gitHead": "813003efe6a7eebbdb78fa5f16ccc8923a305e74"
 }