@noizt/ui

A premium design system for dark, luxury UI experiences. Built for the Noiztbander ecosystem — fashion ecommerce, creative portfolios, and editorial interfaces.

Overview

@noizt/ui is a decoupled, atomic React component library optimized for high-contrast, motion-rich interfaces. It ships both ESM and CJS builds for maximum compatibility.

Core principles:

• Atomic Theming: No global providers. Every component resolves its own tokens via the appearance prop ('dark' | 'light'), enabling "Jewelry Box" layouts where dark and light components coexist freely on the same page.
• React 19: Uses the ref-as-prop pattern — no forwardRef wrappers.
• ESM + CJS: Dual builds via tsup. Tree-shakeable subpath exports.
• Ecommerce Ready: Eleven ecommerce primitives with schema.org structured data for SEO and AI readiness.
• Accessible: WCAG 2.2 AA compliance goal, prefers-reduced-motion support, ARIA roles, and keyboard navigation throughout.

Installation

npm install @noizt/ui

Optional: Three.js Dependencies

To use 3D components (shaders, models, scenes), install these peer dependencies manually:

npm install three @react-three/fiber @react-three/drei postprocessing

Note: @noizt/ui already includes framer-motion as a bundled dependency — no separate installation needed for animations.

Peer Dependencies (Full List)

| Package | Required For | Version | | -------------------- | ----------------------- | ----------- | | react | Core | >=19.0.0 | | three | 3D components | >=0.183.0 | | @react-three/fiber | React + Three.js | >=9.0.0 | | @react-three/drei | Three.js helpers | >=10.0.0 | | postprocessing | Post-processing effects | >=6.35.0 | | lucide-react | Icons | >=0.400.0 |

Quick Start

1. Import Global Styles

Import the core tokens and global resets in your application entry point:

// Complete package — all styles included
import '@noizt/ui/styles'

// Or import individual style files
import '@noizt/ui/styles/globals.css' // Global resets + typography
import '@noizt/ui/styles/tokens.css' // CSS variables only
import '@noizt/ui/styles/motion.css' // Animation keyframes

After importing, all typography tags (h1, h2, h3, p, span, label, etc.) are automatically styled with the design system.

2. Use a Component

import { Button, Card, Heading } from '@noizt/ui/primitives'

export function ProfileHeader() {
  return (
    <Card appearance="dark">
      <Heading appearance="dark">Erick Ureña</Heading>
      <Button appearance="dark" variant="primary">
        View Profile
      </Button>

      {/* Nested light component for the "Jewelry Box" effect */}
      <Card appearance="light" variant="elevated">
        <p>Featured Project</p>
      </Card>
    </Card>
  )
}

3. Ready-to-Use Typography Classes

<h1 class="noizt-h1">Title</h1>
<p class="noizt-body-lg">Large paragraph</p>
<span class="noizt-label">Label</span>
<code class="noizt-mono">Code</code>

| Class | Description | | ------------------------------------------- | ------------------------- | | .noizt-display | Hero/landing display text | | .noizt-h1 through .noizt-h6 | Heading levels | | .noizt-title-h1 through .noizt-title-h3 | Responsive fluid headings | | .noizt-body-lg | Large body text | | .noizt-body | Regular body text | | .noizt-body-sm | Small body text | | .noizt-body-xs | Extra small body text | | .noizt-label | Uppercase label | | .noizt-label-sm | Small uppercase label | | .noizt-mono | Monospace/code |

Component Catalogue

Primitives

| Component | Description | | ------------------- | ------------------------------------------------------------------------- | | AnimatedText | Text with entrance animation | | ArtworkCard | Portfolio card with hover overlay showing media counts | | ArtworkNav | Navigation for artwork galleries | | Avatar | User profile image with initials fallback (circle/square/rounded) | | BackgroundPattern | Static and animated background patterns | | Badge | Status and category labels with variants | | Button | Primary, secondary, ghost, and frosted variants | | Card | Default, elevated, and frosted card containers | | Carousel | Image and content carousel with keyboard navigation | | CircularProgress | Animated percentage indicator (role="progressbar") | | CustomCursor | Custom cursor with effects | | DecorativeOverlay | 18 subtle overlay patterns (grain, scanlines, sci-fi borders, glitch) | | Divider | Horizontal rule with variants | | FloatingNav | Floating navigation bar | | Heading | Typography heading levels | | HistoryItem | Professional timeline entry | | Icon | Lucide React + brand icons wrapper (decorative by default: aria-hidden) | | IconButton | Icon-only button | | Image | Optimized image with lazy loading | | InfiniteScroll | Marquee/carousel with seamless loop | | Link | Styled anchor with hover effects | | Logo | Brand logo component | | MenuToggle | Hamburger-to-X animated toggle | | NotFound | 404 page with decorative overlays | | PageCounter | Scroll-aware section counter (role="status", aria-live) | | PDFVisualizer | PDF embed with fullscreen and download | | RadarChart | Skills radar visualization | | Reveal | Scroll-triggered animation wrapper | | SegmentedControl | Segmented button group | | SoftwareIcon | Tech stack icon registry | | TabGroup | Tab navigation with keyboard support (underline/pill/bordered) | | Text | Typography text component | | TextField | Input field with variants | | TextRing | 3D rotating text ring | | Video | Video player with controls |

Ecommerce

| Component | Description | | ----------------- | ----------------------------------------------------------------- | | AddToCartButton | Add to cart CTA | | CartDrawer | Slide-out cart panel with focus trap and Escape key close | | CartItem | Cart line item (<article> semantic element) | | CheckoutSummary | Order summary with schema.org/PriceSpecification | | CollectionCard | Collection preview with schema.org/CollectionPage microdata | | ColorSelector | Color swatch picker | | ImageGallery | Product image gallery | | Price | Formatted price display with machine-readable content attribute | | ProductCard | Product preview card with schema.org/Product microdata | | ProductGrid | Responsive product grid | | SizeSelector | Size picker |

Compositions

| Component | Description | | ----------------------------- | ------------------------------------------ | | AccountMenu | User account dropdown | | Breadcrumbs | Navigation breadcrumb trail | | CollectionPageLayout | Full collection page layout | | DocumentVisualizer | Document viewer composition | | DropPageLayout | Drop/launch page layout | | FAQAccordion / FAQSection | Collapsible FAQ sections | | FeaturedProductsSection | Featured products grid section | | HeroEditorial | Editorial hero layout | | HeroStage | Hero stage with background and CTA | | ModelCard | 3D model viewer card | | NewsletterCTA | Newsletter signup composition | | ProductCarousel | Full product carousel section | | ProductDetailPage | Full PDP layout (gallery, selectors, CTA) | | ProductListingPage | Full PLP with header, toolbar, grid | | ProductPageLayout | Generic product page wrapper | | ShaderCard | WebGL shader card | | SiteFooter | Site-wide footer | | SlantedGallery | Diagonal image slices with scroll parallax | | TrustBar | Trust signal bar | | UserAvatar | User avatar with metadata |

Accessibility

@noizt/ui targets WCAG 2.2 AA compliance. Accessibility is built into components, not bolted on.

Reduced Motion

All animation components respect the user's prefers-reduced-motion media query. Animations are disabled or simplified when the user has requested reduced motion:

• Reveal — skip entrance animation, render immediately
• InfiniteScroll — pause scroll loop
• Carousel — disable auto-advance and CSS transitions
• TextRing — freeze rotation
• CircularProgress — render static end-state

ARIA Roles

| Component | Role / Pattern | | ------------------ | ----------------------------------------------------------------------------------------- | | CircularProgress | role="progressbar", aria-valuenow, aria-valuemin, aria-valuemax, aria-label | | TabGroup | role="tablist" / role="tab", id/aria-controls wiring, getTabPanelProps() helper | | CartDrawer | role="dialog" (via <dialog> element), aria-expanded, aria-haspopup, focus trap | | PageCounter | role="status", aria-live="polite" | | Carousel | aria-live="polite" slide announcer, tabIndex on viewport | | InfiniteScroll | aria-hidden on duplicated items, aria-label on container |

Schema.org Structured Data

Ecommerce components embed schema.org microdata for SEO and AI readiness:

| Component | Schema | | ----------------- | ------------------------------------------------------------ | | ProductCard | schema.org/Product — itemprop on name, image, offers | | Price | itemprop="price" with machine-readable content attribute | | CartItem | schema.org/Offer | | CheckoutSummary | schema.org/PriceSpecification | | CollectionCard | schema.org/CollectionPage |

Screen Reader Tips

• Icon is aria-hidden={true} by default when no aria-label is provided — prevents duplicate announcements when used alongside text labels.
• TabGroup exports getTabPanelProps() to wire up the associated panel with the correct role="tabpanel", id, and aria-labelledby.
• TextRing accepts an aria-label prop and renders a visually-hidden text fallback for screen readers.
• CartDrawer manages focus: traps focus while open, returns focus to the trigger on close.

Appearance Prop

The appearance prop is the core theming mechanism. Pass 'dark' or 'light' to any component — it resolves its own color tokens locally using resolveTokens(appearance) from src/styles/tokens.ts.

import { Button, Card } from '@noizt/ui/primitives'

// Dark card on a light page — "Jewelry Box" effect
<Card appearance="dark" variant="elevated">
  <Button appearance="dark" variant="primary">Add to Bag</Button>
</Card>

// Light card on a dark page
<Card appearance="light">
  <Button appearance="light" variant="ghost">Cancel</Button>
</Card>

No provider is needed. Components at any nesting depth can independently switch appearance.

Ecommerce Ready

Eleven dedicated ecommerce components cover the full fashion commerce flow:

import {
  ProductCard,
  Price,
  SizeSelector,
  ColorSelector,
  AddToCartButton,
  CartDrawer,
  CartItem,
  CheckoutSummary,
  CollectionCard,
  ImageGallery,
  ProductGrid,
} from '@noizt/ui/ecommerce'

// Product card with schema.org microdata
<ProductCard
  name="Archive Hoodie"
  subtitle="FW25 Collection"
  price={380}
  compareAtPrice={450}
  image="/hoodie.jpg"
  href="/products/archive-hoodie"
  badge="SALE"
  appearance="dark"
/>

// Price with machine-readable content attribute
<Price amount={380} compareAt={450} appearance="dark" size="lg" />

Schema.org microdata is embedded automatically on ProductCard, Price, CheckoutSummary, and CollectionCard, making product data readable by search engines and AI assistants without extra configuration.

TypeScript

All components are fully typed. Props use explicit interfaces — no any. The library ships with bundled type declarations via tsup.

import type { ButtonProps, CardProps, ProductCardProps } from '@noizt/ui'

Package Exports

| Export | Description | | ------------------------ | ------------------------------- | | @noizt/ui | Main entry — all components | | @noizt/ui/primitives | Core UI primitives | | @noizt/ui/ecommerce | Ecommerce components | | @noizt/ui/compositions | Page compositions | | @noizt/ui/hooks | React hooks | | @noizt/ui/styles | CSS tokens (import in app root) | | @noizt/ui/motion | Framer Motion presets |

Development & Storybook

npm run storybook  # Launch branded dev environment at :6006
npm run verify     # lint + format + typescript + tests + build

• Staging: ui-staging.noiztbander.com
• Production: ui.noiztbander.com

Releasing

We use release-please with Conventional Commits:

1. Commit with feat:, fix:, chore:, or refactor: prefixes.
2. Push to main — triggers a Release PR.
3. Merge the Release PR — finalizes versioning, updates CHANGELOG, and triggers production deployment.

Contributing

See AGENTS.md for development conventions and the component checklist.

Credits

• Design & Creative Direction: Erick Ureña
• Engineering: Noizt Team

License

MIT