Zied UI · @zied-snoussi/ui

The component system behind zied-snoussi.vercel.app: UI primitives, visual effects, layout, features and page sections, extracted from the portfolio into a typed, documented and versioned library with a full Storybook.

• Package: @zied-snoussi/ui, published on npm (ESM, TypeScript declarations, "use client" on every module).
• Storybook: every component with controls, docs, accessibility checks, light/dark themes and EN / FR / AR (RTL).
• Tests: every story runs as a browser test (Vitest + Playwright): render, play interactions and axe accessibility checks.
• AI-ready: Storybook MCP server, shadcn MCP, AGENTS.md rules and Claude Code skills, so agents can read, build and test components.
• Releases: automated with Changesets (semantic versioning, changelog, GitHub Releases, npm provenance).

Contents

• What is inside
• Install in a project
• Usage
• Develop locally
• Project structure
• Scripts
• Testing
• AI agents and MCP
• Release process
• CI/CD
• Documentation

What is inside

| Group | Components | Import from | |---|---|---| | UI primitives | Avatar, Badge, Button, Card, Carousel, Dialog, DropdownMenu, ScrollArea, Separator, Sheet, Tabs, plus cn(), format helpers and hooks (useMediaQuery, useIsMobile, useScrollToTop…) | @zied-snoussi/ui | | Effects | SectionHeading, NodeCluster, Trace, CircuitDefs, elbowPath (circuit design language), Particles (WebGL, OGL), DomeGallery (3D draggable gallery), Fade | @zied-snoussi/ui/effects | | Next.js | ThemeProvider, Navbar, Footer, LanguageSwitcher, ThemeToggle, SectionHeader, ScrollToTop, ProjectCard, AIChatbot and its parts (ChatWindow, ChatMessage, ChatInput, ChatHeader, ChatMarkdown, RobotSvg, RobotLauncher), askChatbot() | @zied-snoussi/ui/next | | Styles | Design tokens (light and dark), radius scale, brand colors | @zied-snoussi/ui/theme.css | | Translations | Labels used by the Next.js components | @zied-snoussi/ui/messages/{en,fr,ar}.json | | Sections & pages | Home, About, Work, Education, Skills, Projects, GitHub stats, Ask the bot, Contact, full portfolio page | Storybook only (they depend on the portfolio content) |

Install in a project

pnpm add @zied-snoussi/ui            # or: npm i @zied-snoussi/ui / yarn add @zied-snoussi/ui
pnpm add next next-intl next-themes  # only if you use @zied-snoussi/ui/next

Peer dependencies: react and react-dom 19; next 16, next-intl 4 and next-themes 0.4 for the Next.js entry point.

Usage

Styles (Tailwind CSS v4), in your global CSS:

@import "tailwindcss";
@import "@zied-snoussi/ui/theme.css";

theme.css holds the tokens and an @source directive so Tailwind generates the classes used inside the package. The tokens expect two font variables: --font-inter and --font-jetbrains-mono (set them with next/font/google).

Components:

import { Button, Badge, Card, CardContent } from '@zied-snoussi/ui';
import { SectionHeading, Fade } from '@zied-snoussi/ui/effects';

export function Intro() {
  return (
    <Fade bottom>
      <SectionHeading index="01" label="About" title="Full-Stack AI Engineer" />
      <Card>
        <CardContent className="flex gap-2 pt-6">
          <Badge variant="secondary">RAG</Badge>
          <Button>Contact me</Button>
        </CardContent>
      </Card>
    </Fade>
  );
}

Next.js layout (App Router, next-intl with locales en, fr, ar):

import { NextIntlClientProvider } from 'next-intl';
import { ThemeProvider, Navbar, Footer, AIChatbot } from '@zied-snoussi/ui/next';

<NextIntlClientProvider locale={locale} messages={messages}>
  <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
    <Navbar />
    {children}
    <Footer />
    <AIChatbot /> {/* POST /api/chat → { message: string } */}
  </ThemeProvider>
</NextIntlClientProvider>

Merge @zied-snoussi/ui/messages/<locale>.json into your app messages so the components find their labels. Full guide: docs/USAGE.md.

Develop locally

Requirements: Node.js 22+ (see .nvmrc), pnpm 10.

pnpm install
pnpm storybook        # http://localhost:6006
pnpm build            # library → dist/

In Storybook, the toolbar switches the locale (EN / FR / AR, RTL) and the theme (light / dark). /api/chat and /api/contact are mocked in .storybook/mocks/api.ts.

Project structure

.
├── .changeset/              # pending release notes (Changesets)
├── .claude/skills/          # Claude Code skills (add-component, write-stories, fix-a11y, release)
├── .mcp.json                # MCP servers for Claude Code (also .cursor/, .vscode/)
├── .github/workflows/       # ci.yml, release.yml, storybook.yml
├── .storybook/              # Storybook config, providers, API mocks
├── docs/                    # architecture, usage, contributing, release guides
├── public/assets/           # images used by the stories
├── src/
│   ├── components/
│   │   ├── ui/              # primitives + effects (each with *.stories.tsx)
│   │   ├── shared/          # SectionHeader, Fade, ScrollToTop
│   │   ├── layout/          # Navbar, Footer, LanguageSwitcher, ThemeToggle
│   │   ├── features/        # ProjectCard, ProjectDetail, AI chatbot
│   │   ├── sections/        # page sections (Storybook reference)
│   │   └── providers/       # ThemeProvider
│   ├── entries/             # npm entry points: index.ts, effects.ts, next.ts
│   ├── data/ messages/      # portfolio content and translations
│   ├── i18n/ lib/ types/    # routing, utils, hooks, types
│   └── styles/globals.css   # design tokens (source of theme.css)
├── stories/                 # MDX docs (Introduction, Getting Started, Foundations) and full page
├── AGENTS.md / CLAUDE.md    # rules for AI agents
├── vitest.config.ts         # story tests (Vitest browser mode + Playwright)
├── tsup.config.ts           # library build
└── eslint.config.js

Scripts

| Script | What it does | |---|---| | pnpm storybook | Storybook dev server on port 6006 | | pnpm build-storybook | Static Storybook in storybook-static/ | | pnpm build | Library build with tsup (ESM + .d.ts + theme.css + messages) | | pnpm dev | Library build in watch mode | | pnpm typecheck | TypeScript, no emit | | pnpm lint | ESLint (TypeScript, React hooks, Storybook rules) | | pnpm test | Story tests in Chromium (render, interactions, a11y) | | pnpm test:coverage | Same, with a V8 coverage report | | pnpm check | typecheck + lint + test + build + build-storybook (what CI runs) | | pnpm changeset | Describe a change for the next release |

Testing

pnpm test             # every story: render + play interactions + accessibility (Chromium)
pnpm test:coverage    # with coverage report

61 tests today, including interaction tests for buttons, dialogs, sheets, menus, tabs, the carousel, the language switcher, the AI chatbot and the contact form. Details: docs/TESTING.md. Known accessibility issues inherited from the portfolio: docs/ACCESSIBILITY.md.

AI agents and MCP

Open the repo in Claude Code, Cursor or VS Code: the MCP servers are preconfigured (.mcp.json, .cursor/mcp.json, .vscode/mcp.json). The public storybook server works with nothing running; storybook-dev needs pnpm storybook.

Use the public server in any project that consumes the library:

claude mcp add --transport http zied-ui https://zied-ui-mcp.vercel.app/mcp

| Server | What agents can do | |---|---| | storybook (https://zied-ui-mcp.vercel.app/mcp) | public, always on: list components, read props, stories and docs of the published Storybook (https://zied-snoussi.github.io/zied-ui/) | | storybook-dev (http://localhost:6006/mcp) | while pnpm storybook runs: docs of your local changes, story-writing instructions, run tests, preview URLs | | shadcn | browse and add shadcn/ui primitives |

Rules for agents: AGENTS.md (imported by CLAUDE.md). Claude Code skills in .claude/skills/: add-component, write-stories, fix-a11y, release. Guide: docs/AI-WORKFLOW.md.

Release process

Versioning follows Semantic Versioning and is automated with Changesets:

1. In your branch, run pnpm changeset, pick patch / minor / major and describe the change. Commit the generated file in .changeset/.
2. Open a pull request. CI must pass.
3. After merge to main, the Release workflow opens (or updates) a "Version packages" pull request that bumps the version and writes CHANGELOG.md.
4. Merging that pull request publishes @zied-snoussi/ui to npm (with provenance) and creates a tagged GitHub Release with the changelog.

Details: docs/RELEASING.md.

CI/CD

| Workflow | Trigger | Jobs | |---|---|---| | ci.yml | Pull requests, pushes to main | Typecheck & lint · story tests with coverage (Chromium) · library build, package check and smoke test · Storybook build · artifacts | | release.yml | Pushes to main | Changesets: version PR, or publish to npm (provenance) + GitHub Release | | storybook.yml | Manual / releases | Builds Storybook and deploys it to GitHub Pages (enable Pages first) |

Documentation

• docs/ARCHITECTURE.md: layers, entry points, build, styling and i18n decisions
• docs/USAGE.md: consuming the package in Next.js and plain React apps
• docs/COMPONENTS.md: catalog with props and examples
• docs/RELEASING.md: versioning, publishing and tokens
• docs/TESTING.md: story tests, interactions, coverage
• docs/ACCESSIBILITY.md: a11y gate and known issues
• docs/AI-WORKFLOW.md: MCP servers, skills and agent workflow
• CONTRIBUTING.md: adding a component, story and docs checklist
• CHANGELOG.md

License

MIT © 2026 Zied Snoussi