Feat/v0.3 icon button

.github/workflows/ci.yml

@@ -33,6 +33,9 @@ jobs:
       - name: Install dependencies
         run: yarn install --frozen-lockfile
 
+      - name: Install Playwright Chromium
+        run: yarn playwright install --with-deps chromium
+
       - name: Type check
         run: yarn type-check
 
@@ -47,3 +50,34 @@ jobs:
 
       - name: Build Storybook
         run: yarn build-storybook
+
+      - name: Verify package consumers
+        run: yarn test:consumers
+
+      - name: Accessibility checks
+        run: yarn test:a11y
+
+  visual-regression:
+    name: Visual regression
+    runs-on: windows-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: yarn
+          cache-dependency-path: yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Install Playwright Chromium
+        run: yarn playwright install chromium
+
+      - name: Visual regression checks
+        run: yarn test:visual

CHANGELOG.md

@@ -10,11 +10,16 @@ Update `[Unreleased]` during normal development. Before a release, move relevant
 
 ### Added
 
-- Initial documentation experience structure.
+- V1 editorial catalog and release-readiness documentation.
+- `IconButton`, an accessible icon-only action primitive with loading support.
+- Playwright visual and axe scripts.
+- Tarball-based React + Vite and Next.js App Router consumer validation.
 
 ### Changed
 
-- Nothing yet.
+- Button now defaults to `type="button"`.
+- Progress now has the default accessible name `Progress` when no contextual label is supplied.
+- Styled-components imports use the v6 named `styled` export for ESM compatibility.
 
 ### Deprecated
 
@@ -26,7 +31,8 @@ Update `[Unreleased]` during normal development. Before a release, move relevant
 
 ### Fixed
 
-- Nothing yet.
+- ESM and CommonJS package artifacts now load styled-components correctly.
+- CommonJS distribution now uses a `.cjs` file extension under the ESM package boundary.
 
 ### Security
 

README.md

@@ -1,6 +1,6 @@
 # FeitozaUI
 
-> A React and TypeScript UI Engineering Platform focused on foundations, primitives, component APIs, accessibility, testing, documentation, and future package distribution.
+> A compact React and TypeScript component library focused on foundations, accessible APIs, testing, documentation, and verified package distribution.
 
 ![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)
 ![React](https://img.shields.io/badge/React-19-61dafb)
@@ -9,32 +9,33 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 ![npm](https://img.shields.io/badge/npm-not%20published-lightgrey)
 
-FeitozaUI is not just a set of isolated components. It is being built as a small but professional component platform that documents engineering decisions, public APIs, design foundations, accessibility rules, testing strategy, and package readiness.
+FeitozaUI is a deliberately small component platform for practical React interfaces. It documents public APIs, design foundations, accessibility rules, testing strategy, and package-readiness decisions rather than growing an unbounded component catalog.
 
 ## Features
 
 - React and TypeScript-first component APIs.
 - Public package surface with foundational atoms, core molecules, and design tokens.
 - Storybook documentation for foundations, primitives, guidelines, accessibility, and roadmap.
-- Vite library build with ESM, CJS, UMD, and bundled TypeScript declarations.
+- Vite library build with verified ESM, CJS, UMD, and bundled TypeScript declarations.
 - Vitest and Testing Library coverage for public components.
 - Architecture docs, ADRs, component guidelines, release planning, and maintenance docs.
 
 ## Current Status
 
-FeitozaUI is a work in progress. The current package surface is intentionally small and focused on quality before breadth.
+FeitozaUI V1 is intentionally compact and focused on quality before breadth. The package is ready for a manual first release, but is not published to npm yet.
 
 Current:
 
-- Public components: `Button`, `Box`, `Flex`, `Surface`, `Badge`, `Divider`, `Spinner`, `Skeleton`, `Progress`, `Input`, `Textarea`, `Select`, `Alert`, `EmptyState`, `Tabs`, `Card`.
+- Editorial V1 catalog: `Button`, `Checkbox`, `Radio`, `RadioGroup`, `Input`, `Textarea`, `Select`, `Tabs`, `Surface`, and `Card`.
+- Supporting public primitives: `Badge`, `Box`, `Divider`, `EmptyState`, `Field`, `Flex`, `IconButton`, `Progress`, `Skeleton`, `Spinner`, and `VisuallyHidden`.
 - Foundations: colors, typography, spacing, radii, motion, borders, focus, states, and semantic mappings.
-- Package build validated locally.
+- Package artifacts verified through local tarball consumers for React + Vite and Next.js App Router.
 - Storybook structured as the documentation surface.
 - Accessibility and behavior coverage across the active public surface.
 
 Not current:
 
-- Published npm package.
+- Published npm package (manual publication is the remaining external release action).
 - Full theme system.
 - Complete component catalog.
 - BFF, micro-frontends, or production showcase.
@@ -57,7 +58,7 @@ The future package name is:
 @feitoza-ui/core
 ```
 
-Current public exports:
+The V1 editorial catalog is documented in [V1 Scope](docs/V1.md). Current public exports include:
 
 ```ts
 export {
@@ -66,25 +67,29 @@ export {
   Box,
   Button,
   Card,
+  Checkbox,
   Divider,
   EmptyState,
+  Field,
   Flex,
+  IconButton,
   Input,
   Progress,
+  Radio,
+  RadioGroup,
   Select,
   Skeleton,
   Spinner,
   Surface,
   Tabs,
-  Textarea
+  Textarea,
+  VisuallyHidden
 } from '@feitoza-ui/core';
 ```
 
 ## Installation
 
-The package is not published yet. Installation is future work.
-
-Future installation:
+The package is not published yet. After the first manual publish:
 
 ```bash
 npm install @feitoza-ui/core
@@ -106,6 +111,7 @@ Build the package locally:
 
 ```bash
 yarn.cmd build
+yarn.cmd test:consumers
 ```
 
 ## Usage
@@ -179,7 +185,7 @@ The project uses Vitest and Testing Library.
 yarn.cmd test --run
 ```
 
-Current tests cover rendering, interactions, disabled behavior, ref forwarding, native prop pass-through, layout props, and basic accessibility expectations for primitives.
+Current tests cover rendering, interactions, keyboard behavior, disabled behavior, ref forwarding, native prop pass-through, controlled state, form semantics, and accessibility expectations for primitives.
 
 See [Testing Strategy](docs/TESTING_STRATEGY.md).
 
@@ -196,6 +202,24 @@ It currently documents Overview, Getting Started, Foundations, Components, Guide
 
 See [Storybook Strategy](docs/STORYBOOK.md).
 
+## Release Validation
+
+Run the complete local release-readiness set:
+
+```bash
+yarn.cmd lint
+yarn.cmd type-check
+yarn.cmd test --run
+yarn.cmd build
+yarn.cmd build-storybook
+yarn.cmd test:a11y
+yarn.cmd test:visual
+yarn.cmd test:consumers
+npm.cmd pack --dry-run
+```
+
+`test:consumers` packs the library, installs that exact tarball into the React + Vite and Next.js fixtures, and runs their type-check and production builds.
+
 ## Roadmap
 
 The roadmap is maintained in [docs/roadmap/ROADMAP.md](docs/roadmap/ROADMAP.md).

docs/README.md

@@ -16,6 +16,7 @@ Use it to understand the project vision, architecture, component platform decisi
 - [Decisions](architecture/DECISIONS.md): ADR index and decision process.
 - [API Conventions](architecture/API_CONVENTIONS.md): public component API rules.
 - [ADRs](architecture/adr): architecture decision records.
+- [V1 Scope](V1.md): frozen editorial catalog, API boundaries, and release validation.
 
 ## AI Guidance
 

docs/V1.md

@@ -0,0 +1,50 @@
+# V1 Scope
+
+FeitozaUI V1 is a compact, public React component package. Its goal is to demonstrate dependable component engineering, not to compete on catalog size.
+
+## Editorial Catalog
+
+- Button
+- Checkbox
+- Radio
+- RadioGroup
+- Input
+- Textarea
+- Select
+- Tabs
+- Surface
+- Card
+
+Other existing public primitives remain available and documented in Storybook, but do not expand the V1 delivery scope.
+
+## API Boundaries
+
+- `Button` defaults to `type="button"`; pass another native type explicitly for form submission.
+- `Field` composes labels, helper text, error text, and shared state for `Input`, `Textarea`, and `Select`.
+- `Checkbox` and `Radio` preserve their independent native control structures because their indicator and label layouts differ from text controls.
+- `Box` is a layout primitive, `Surface` provides visual containment, and `Card` is the default padded content grouping built on that containment.
+- `Progress` always exposes an accessible name. Use `label` to provide a contextual one.
+- Every `Tabs.Trigger` and matching `Tabs.Content` must use a unique, stable `value` within the same `Tabs.Root`.
+
+## Distribution Contract
+
+The package exports ESM, CommonJS, UMD, and rolled-up TypeScript declarations from the package root. React, React DOM, and styled-components are peer dependencies.
+
+The release check packs the exact artifact and validates it in two external fixtures:
+
+- React + Vite
+- Next.js App Router
+
+## V1 Validation
+
+```bash
+yarn.cmd lint
+yarn.cmd type-check
+yarn.cmd test --run
+yarn.cmd build
+yarn.cmd build-storybook
+yarn.cmd test:a11y
+yarn.cmd test:visual
+yarn.cmd test:consumers
+npm.cmd pack --dry-run
+```

docs/architecture/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 FeitozaUI is currently a React and TypeScript project with a Next.js app, Storybook, Vite library build, Styled Components, Vitest, and Testing Library.
 
-The target architecture is a UI Engineering Platform with clear separation between reusable package code, documentation, and future examples.
+The architecture is a UI Engineering Platform with clear separation between reusable package code, documentation, and future examples.
 
 ## Current Architecture
 
@@ -15,7 +15,7 @@ The target architecture is a UI Engineering Platform with clear separation betwe
 
 ## Core Package
 
-The core package should eventually expose reusable foundations, primitives, components, and types through a stable public API. It should not depend on the showcase.
+The core package exposes reusable foundations, primitives, components, and types through a stable root public API. It does not depend on the showcase.
 
 Target package name: `@feitoza-ui/core`.
 
@@ -31,13 +31,9 @@ Storybook is the primary documentation and exploration surface. It should explai
 
 The Vite build should generate package outputs that match `package.json` exports. Build files and publishing settings should be verified before any release.
 
-## Current Limits
+## V1 Boundary
 
-- The package identity still needs alignment.
-- Public exports need to be made explicit.
-- Foundations need stronger structure.
-- Storybook needs professional documentation polish.
-- Publishing is future work.
+V1 freezes the editorial catalog at Button, Checkbox, Radio, RadioGroup, Input, Textarea, Select, Tabs, Surface, and Card. Supporting primitives remain public, but do not expand the V1 documentation scope. See [V1 Scope](../V1.md).
 
 ## Future Possibilities
 

docs/design-system/DX.md

@@ -12,7 +12,7 @@ import { Button } from '@feitoza-ui/core';
 
 ## Predictable APIs
 
-Components should use consistent prop names for shared concepts such as `variant`, `size`, `disabled`, and `loading`.
+Components should use consistent prop names for shared concepts such as `variant`, `size`, and `disabled`. A state prop such as `loading` is added only when the component has a defined loading contract.
 
 ## Autocomplete And IntelliSense
 
@@ -33,7 +33,7 @@ Names should match the language of the platform. Avoid mixing product-specific n
 ## Good API Example
 
 ```tsx
-<Button variant="primary" size="md" disabled>
+<Button variant="primary" disabled>
   Save
 </Button>
 ```

eslint.config.js

@@ -13,7 +13,9 @@ const eslintConfig = [
     ignores: [
       'node_modules/**',
       '.next/**',
+      '**/.next/**',
       'dist/**',
+      '**/dist/**',
       'build/**',
       'coverage/**',
       'out/**',

package.json

@@ -7,14 +7,14 @@
   "license": "MIT",
   "author": "Maria Fernanda",
   "type": "module",
-  "main": "./dist/feitoza-ui.cjs.js",
+  "main": "./dist/feitoza-ui.cjs",
   "module": "./dist/feitoza-ui.es.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/feitoza-ui.es.js",
-      "require": "./dist/feitoza-ui.cjs.js"
+      "require": "./dist/feitoza-ui.cjs"
     }
   },
   "files": [
@@ -64,7 +64,10 @@
     "type-check": "tsc --noEmit",
     "coverage": "vitest run --coverage",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "test:visual": "playwright test -c playwright.visual.config.ts",
+    "test:a11y": "playwright test -c playwright.accessibility.config.ts",
+    "test:consumers": "node scripts/verify-consumers.mjs"
   },
   "lint-staged": {
     "*.{ts,tsx}": [

playwright.accessibility.config.ts

@@ -6,13 +6,14 @@ export default defineConfig({
   fullyParallel: false,
   workers: 1,
   reporter: 'list',
+  webServer: {
+    command: 'yarn build:docs && yarn start:docs -p 3100',
+    port: 3100,
+    reuseExistingServer: !process.env.CI
+  },
   use: {
     baseURL: 'http://127.0.0.1:3100',
     browserName: 'chromium',
-    launchOptions: {
-      executablePath:
-        'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe'
-    },
     locale: 'en-US',
     trace: 'off',
     video: 'off',

playwright.visual.config.ts

@@ -6,13 +6,14 @@ export default defineConfig({
   fullyParallel: false,
   workers: 1,
   reporter: 'list',
+  webServer: {
+    command: 'yarn build:docs && yarn start:docs -p 3100',
+    port: 3100,
+    reuseExistingServer: !process.env.CI
+  },
   use: {
     baseURL: 'http://127.0.0.1:3100',
     browserName: 'chromium',
-    launchOptions: {
-      executablePath:
-        'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe'
-    },
     locale: 'en-US',
     trace: 'off',
     video: 'off',