Novus — Fynd's Design System

Novus is a comprehensive React + TypeScript design system developed for Fynd products, providing a consistent, accessible, and performant foundation for building user interfaces across internal and partner teams. It offers a complete set of production-ready components, design tokens, and best practices that streamline development while ensuring high-quality user experiences and maintainability.

Key Principles

• Consistency: Unified visual language and component behavior across all Fynd products
• Usability: Intuitive components designed with user experience at the forefront
• Performance: Optimized bundle sizes, tree-shaking support, and efficient rendering
• Accessibility: WCAG 2.1 AA compliance with keyboard navigation, ARIA support, and screen reader compatibility
• Theming: Flexible token system supporting light/dark modes and brand customization

Getting Started

Installation

Install Novus via npm, yarn, or pnpm:

npm install novus
# or
yarn add novus
# or
pnpm add novus

Basic Usage

import { Button } from "novus";

export default function App() {
  return <Button appearance="primary">Hello</Button>;
}

TypeScript Support

Novus is built with TypeScript and provides full type definitions. All components export their prop types for enhanced type safety and developer experience. TypeScript support is included out of the box—no additional @types package required.

Design Tokens (Overview)

Design tokens are the foundational design decisions of Novus, abstracted into reusable variables that ensure visual consistency across components. Tokens serve as the single source of truth for spacing, colors, typography, radii, shadows, z-index values, and motion preferences.

Token Groups

• Colors: Semantic color palette including primary, secondary, success, error, warning, and neutral shades with support for light and dark themes
• Spacing: Consistent spacing scale (xs, s, m, l, xl, etc.) used for margins, padding, and gaps
• Typography: Font families, sizes, weights, line heights, and letter spacing for display, heading, and body text variants
• Radii: Border radius values for buttons, cards, inputs, and other rounded elements
• Shadows: Elevation system using shadow tokens to create depth and hierarchy
• Z-Index: Layering system for modals, tooltips, popovers, and dropdowns
• Motion: Animation durations, easing functions, and motion preferences respecting prefers-reduced-motion

Token Implementation

Tokens flow into components through CSS custom properties (CSS variables) or Less variables, depending on the build setup. Components reference token values rather than hardcoded styles, enabling theme switching and customization. The ThemeProvider component manages token distribution and theme application throughout the component tree.

Theming Strategy

Novus supports multiple theming approaches:

• Light/Dark Mode: Automatic theme switching based on system preferences or explicit user selection
• Brand Skins: Customizable color palettes for different product lines
• CSS Variables: Runtime theme updates without requiring a rebuild

Components

Novus provides a comprehensive library of production-ready React components. Each component is fully typed, accessible, and themable.

Component Index

Component	Description	Category
Accordion	Collapsible content sections for organizing and displaying hierarchical information in a compact format	Layout
Avatar	User profile pictures with support for images, icons, text initials, and status indicators	Display
Badge	Compact indicators for labels, notifications, or status information with multiple states and sizes	Feedback
Breadcrumb	Navigation trail showing the current page location within a site hierarchy	Navigation
Button	Primary interactive element supporting multiple types, appearances, sizes, and icon placements	Form
Checkbox	Binary selection input for forms, lists, and settings with support for indeterminate state	Form
CounterBadge	Numeric badge overlay for displaying counts, notifications, or quantities on icons and avatars	Feedback
Divider	Visual separator component for dividing content sections horizontally or vertically	Layout
Feedback	Component for displaying user feedback messages, alerts, and status notifications	Feedback
FilterPill	Chip-style component for displaying and managing active filters in search and data views	Form
FormStep	Individual step container within a multi-step form workflow	Form
FormStepper	Multi-step form navigation component displaying progress through sequential form stages	Form
Icon	SVG icon component supporting the Novus icon set with customizable size and color	Display
IconButton	Button variant containing only an icon, optimized for toolbars, headers, and compact interfaces	Form
Input	Text input field supporting various types (text, number, password, OTP) with validation and tooltips	Form
Link	Anchor component styled consistently with Novus design tokens, supporting internal and external navigation	Navigation
Menu	Dropdown menu container with search, navigation links, breadcrumbs, and footer support	Navigation
MenuItem	Individual menu item component used within Menu for creating selectable navigation or action lists	Navigation
Modal	Overlay dialog component for important content, confirmations, or multi-step flows with customizable header and footer	Feedback
MultiSelect	Select input allowing multiple option selection with search, filtering, and tag display capabilities	Form
NotificationBanner	Persistent notification component for displaying important system messages and alerts	Feedback
Pagination	Component for navigating through paginated data with configurable page size options	Navigation
Popover	Contextual floating panel that appears on interaction, typically containing additional actions or information	Feedback
ProgressBar	Progress indicator showing completion status as linear or circular bars with optional labels and values	Feedback
Radio	Single selection input for mutually exclusive options in forms and choice groups	Form
Select	Dropdown selection component for choosing single values from a list of options with support for grouping and custom content	Form
SelectorDropdown	Specialized dropdown component for selector-based navigation or filtering interfaces	Navigation
SelectorTabs	Tab-based selector component allowing users to switch between different views or filter options	Navigation
Shimmer	Loading placeholder component that displays animated shimmer effects while content is being fetched	Feedback
Slider	Range input component for selecting numeric values along a continuous scale with custom min/max and step controls	Form
Spinner	Loading indicator with optional label positioned around the spinner animation	Feedback
Tab	Individual tab item component used within Tabs for creating tabbed navigation interfaces	Navigation
Tabs	Tabbed navigation container supporting primary and secondary variants with fixed or overflow layouts	Navigation
Tag	Label component for categorizing, organizing, or marking items with optional close actions	Display
TextArea	Multi-line text input component for longer form entries with character count and validation support	Form
ThemeProvider	Root provider component that applies Novus theme tokens and manages theme context throughout the application	Layout
Toggle	Binary switch component for settings and preferences with on/off states	Form
Tooltip	Contextual information overlay that appears on hover or focus, providing additional details about elements	Feedback
Typography	Text component providing semantic typography variants (display, heading, body) with responsive sizing	Display
UploadButton	File upload trigger button component with support for single or multiple file selection	Form
UploadDropZone	Drag-and-drop file upload area component for accepting files through drop interactions	Form

Usage Patterns

Composition Guidelines

Novus components are designed to work together seamlessly. Common composition patterns include:

• Icons in Buttons: Use Icon components with prefixIconName or suffixIconName props on Button, or nest Icon directly in IconButton
• Form Fields: Combine Input, TextArea, or Select with Typography labels and helper text for complete form field compositions
• Feedback Patterns: Use Modal with Button groups in the footer, or Tooltip with interactive elements for contextual help
• Navigation: Pair Tabs with Tab children, or Menu with MenuItem children for hierarchical navigation structures

Layout Patterns

• Spacing: Use consistent spacing tokens between components (typically m or l for major sections)
• Grid Systems: Components are built to work with CSS Grid or Flexbox layouts; use container components for alignment
• Responsive Design: Components adapt to container sizes; use responsive utilities for breakpoint-specific behavior

State Management

Novus components support both controlled and uncontrolled patterns:

• Controlled: Use value and onChange props when you need to manage state externally (React state, Redux, etc.)
• Uncontrolled: Omit value to let the component manage its own internal state
• Default Values: Use defaultValue for uncontrolled components that need initial values

When to use controlled vs uncontrolled:

• Use controlled for form libraries (React Hook Form, Formik), complex validation, or when state must sync with external systems
• Use uncontrolled for simple forms, standalone components, or when state management overhead isn't needed

Accessibility (a11y)

Novus is committed to building accessible interfaces that work for everyone. All components are designed and tested to meet WCAG 2.1 Level AA standards.

Keyboard Navigation

• Tab Navigation: All interactive components are keyboard accessible via Tab and Shift+Tab
• Arrow Keys: List components (Menu, Select, Tabs) support arrow key navigation
• Enter/Space: Standard activation keys for buttons, links, and interactive elements
• Escape: Closes modals, popovers, dropdowns, and other overlay components
• Focus Indicators: Visible focus rings on all interactive elements using Novus token-based styling

ARIA Support

• Semantic HTML: Components use appropriate HTML elements (button, nav, dialog, etc.)
• ARIA Roles: Applied where semantic HTML is insufficient (role="dialog", role="menu", role="tablist")
• ARIA Attributes: aria-label, aria-labelledby, aria-describedby, aria-expanded, aria-selected, and aria-hidden are used appropriately
• Live Regions: Announced for dynamic content updates (e.g., loading states, validation messages)

Screen Reader Support

• Labeling: All form inputs have associated labels (visible or via aria-label)
• Descriptions: Helper text and error messages are properly associated with inputs
• State Announcements: Component states (open/closed, selected/unselected, loading/loaded) are announced to screen readers
• Landmarks: Navigation components use semantic landmarks for quick page navigation

Color and Contrast

• WCAG AA Compliance: Text and interactive elements meet 4.5:1 contrast ratio (normal text) and 3:1 (large text)
• Color Independence: Information is never conveyed by color alone; icons, text, or patterns supplement color-coded states
• Focus Visibility: Focus indicators have sufficient contrast against all background colors

Motion Preferences

• Respects prefers-reduced-motion: Animations and transitions are reduced or eliminated when users prefer reduced motion
• Essential Motion Only: Animations serve a functional purpose (e.g., loading indicators, progress updates)
• Accessible Transitions: Motion respects user preferences while maintaining usability

Performance

Novus is optimized for performance at every level, from bundle size to runtime efficiency.

Bundle Considerations

• Tree Shaking: Components are exported individually; unused components are eliminated from production builds
• Code Splitting: Large components (Modals, complex forms) can be lazy-loaded to reduce initial bundle size
• Dependency Management: Minimal external dependencies; internal utilities are optimized for size

Rendering Optimization

• Memoization: Use React.memo for list items and frequently re-rendered components
• Callback Stability: Callback props are memoized internally where appropriate; memoize user-provided callbacks when passing to list components
• Virtualization: Large lists (in Select, Menu) use virtualization to render only visible items

Best Practices

• Avoid Heavy Render Loops: Keep render functions lightweight; defer expensive computations with useMemo or useCallback
• Lazy Loading: Use React.lazy() for components that aren't immediately visible (modals, complex forms, secondary views)
• Debouncing: Debounce search inputs, filters, and other frequently-updated controlled inputs
• Loading States: Use Spinner, Shimmer, or ProgressBar for async operations to prevent layout shifts and improve perceived performance

Theming & Customization

Novus provides multiple pathways for customization while maintaining design system consistency.

Token Overrides

Design tokens can be overridden at different levels:

• Global Override: Provide custom tokens to ThemeProvider to replace default values across all components
• Component-Level: Use CSS custom properties scoped to specific components for localized customization
• CSS Variables: Modify CSS variables in your stylesheet to update token values at runtime

Component Customization

• className Prop: All components accept className for additional styling via CSS or CSS-in-JS
• Style Props: Inline style prop support for one-off customizations (use sparingly)
• Less Variables: If using Less, override component-specific variables (where available)

Extending Components

• Composition: Build complex components by composing Novus primitives rather than modifying internals
• Wrappers: Create wrapper components that enhance Novus components with additional behavior or styling
• Custom Variants: Use className and token overrides to create custom variants while staying within the design system

Important: Avoid modifying component internals or bypassing the design system; instead, use the provided customization mechanisms to ensure updates and compatibility.

Contributing

Contributing to Novus helps improve the design system for all Fynd products and partner teams.

Proposing Changes

1. Component Changes: Open an issue or discussion for new components, props, or variants before submitting a PR
2. Documentation Updates: Documentation improvements are always welcome; ensure examples use the latest API
3. Bug Reports: Include component version, browser/environment, steps to reproduce, and expected vs actual behavior

Pull Request Guidelines

• Description: Provide clear description of changes, linking to related issues
• Examples: Include code examples demonstrating the change (if applicable)
• Documentation: Update relevant .md files for component changes
• Types: Ensure TypeScript types are updated and exported correctly
• Tests: Include unit tests or update existing tests for behavior changes

Development Workflow

1. Linting: Run linting checks (npm run lint) and fix any errors before committing
2. Type Checks: Verify TypeScript compilation passes (npm run type-check)
3. Preview Docs: Preview documentation locally to ensure formatting and examples render correctly
4. Self-Review: Review your own PR diff before requesting review

Review Process

• All PRs require at least one approval from design system maintainers
• Feedback will be provided within 2 business days
• Address review feedback promptly or discuss proposed changes if clarification is needed

Versioning & Release

Novus follows Semantic Versioning (SemVer) for release management.

Version Format

• Major (x.0.0): Breaking changes that require code updates
• Minor (0.x.0): New features, components, or props (backward compatible)
• Patch (0.0.x): Bug fixes, documentation updates, or minor improvements

Changelog

Release notes and changelog are maintained in the repository. Check the changelog before upgrading to understand changes, deprecations, and migration paths.

Upgrade Guide

When upgrading:

1. Review the changelog for the target version
2. Check for deprecation warnings in your codebase
3. Test components in a staging environment before production deployment
4. Update any deprecated prop usage following migration guides

FAQ

Import Paths

Q: How do I import components?
A: All components are imported from the "novus" package: import { Button, Input } from "novus";. Individual component imports are supported for tree-shaking.

CSS Requirements

Q: Do I need to import CSS separately?
A: Novus includes styles automatically. No separate CSS import is required. Ensure ThemeProvider wraps your application root for token distribution.

SSR and Next.js

Q: Does Novus work with Next.js or server-side rendering?
A: Yes, Novus components support SSR. Some components (Tooltip, Popover, Modals) may require client-side hydration; use Next.js dynamic imports with ssr: false for these if needed.

Icon Usage

Q: How do I use icons?
A: Use the Icon component with icon names: <Icon name="ic_add" />. Icon names reference the Novus icon set. See the Icon component documentation for the full icon list.

Custom Themes

Q: Can I customize colors and styles?
A: Yes, provide custom tokens to ThemeProvider or override CSS variables. See the Theming & Customization section for details.

Browser Support

Q: Which browsers are supported?
A: Novus supports modern browsers (Chrome, Firefox, Safari, Edge) with ES6+ support. IE11 is not supported.

Component Sizes

Q: What size options are available?
A: Most components support a size prop with values: xs, s, m, l, xl. Check individual component documentation for specific size support.

Form Integration

Q: Can I use Novus with React Hook Form / Formik?
A: Yes, Novus components work with popular form libraries. Use controlled mode (value/onChange) for integration. See component docs for form-specific examples.

Roadmap

Novus is continuously evolving. Upcoming improvements include:

• Additional form components (DatePicker, TimePicker, RichTextEditor)
• Enhanced data visualization components (Charts, DataTable)
• Mobile-optimized components and gestures
• Expanded theming capabilities (CSS-in-JS support, theme builder)
• Performance optimizations (further bundle size reduction, rendering improvements)
• Accessibility enhancements (expanded keyboard shortcuts, screen reader improvements)

For detailed roadmap information and to request features, see the project issue tracker.

License

Proprietary — © Fynd. All rights reserved.

Novus is internal software developed for Fynd products and partner integrations. Usage is subject to Fynd's software license agreement.

Acknowledgments

Novus is built and maintained by the Fynd Design System team with contributions from product teams across the organization. Special thanks to all internal and partner teams who provide feedback and drive continuous improvement of the design system.

---

✅ Self-Check (for this README)

• ✅ All component .md files are linked with case-exact names (41 components linked)
• ✅ Components are listed alphabetically with one-line descriptions
• ✅ All usage examples import from "novus"
• ✅ Tokens, a11y, performance, theming, and contribution sections are present and useful
• ✅ No TODOs/placeholders remain beyond badge placeholders (version/build/license)
• ✅ README stands alone (someone can start using Novus without opening any other file)