# @itech-india/itech-fluentui - Complete Documentation > **Complete design system and UI component library built on Microsoft FluentUI v9** > > **🔒 PRIVATE PACKAGE - iTech Internal Use Only** **Version:** 1.0.1 (85+ Components) **License:** MIT **Author:** iTech Design Team --- # 📑 Table of Contents 1. [Overview](#overview) 2. [Installation](#installation) 3. [Quick Start](#quick-start) 4. [Design Tokens](#design-tokens) 5. [Components](#components) 6. [Themes](#themes) 7. [React Hooks](#react-hooks) 8. [Component Development Workflow](#component-development-workflow) 9. [Publishing to npm (private)](#publishing-to-npm-private) 10. [GitHub Actions Setup](#github-actions-setup) 11. [Quick Reference](#quick-reference) 12. [Troubleshooting](#troubleshooting) --- # Overview ## What is @itech-india/itech-fluentui? `@itech-india/itech-fluentui` is the **single UI system** for all internal iTech products. It provides: - ✅ **2000+ Design Tokens** - Extracted directly from Figma - ✅ **4 Brand Variants** - Multi-brand support (brand_1, irepo, blue, vivid_blue) - ✅ **8 Complete Themes** - Light & Dark modes for each brand - ✅ **85+ Production Components** - FluentUI v9 components - ✅ **200+ Icons** - Organized FluentUI icon system - ✅ **Full TypeScript Support** - 100% type-safe with IntelliSense - ✅ **React Hooks** - Easy theme and brand management - ✅ **Zero Configuration** - Works out of the box - ✅ **Tree-shakeable** - Import only what you need ## Architecture ``` ┌─────────────────────────────────────────────────────────┐ │ @itech-india/itech-fluentui (Single npmjs.com Private Artifact) │ │ ┌───────────────────────────────────────────────────┐ │ │ │ All UI Components (44+ components) │ │ │ │ Design Tokens (2000+ from Figma) │ │ │ │ Themes (4 brands × 2 modes = 8 themes) │ │ │ │ Icons (200+ FluentUI icons) │ │ │ └───────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ │ │ npm install @itech-india/itech-fluentui │ ┌───────────┼───────────┐ │ │ │ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │ App 1 │ │ App 2 │ │ App 3 │ ... (5+ apps) └────────┘ └────────┘ └────────┘ ``` **Key Principle:** One source of truth. All UI components live in `@itech-india/itech-fluentui`. All apps consume the same package. --- # Installation ## Prerequisites - Node.js 16+ - npm 7+ or yarn 1.22+ or pnpm - React 18+ ## Install Package **Note:** The package is hosted on **npmjs.com**. Configure `.npmrc` before installing: ```bash echo "@itech-india:registry=https://registry.npmjs.org" >> ~/.npmrc echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" >> ~/.npmrc ``` Once configured: ```bash npm install @itech-india/itech-fluentui@latest # or yarn add @itech-india/itech-fluentui@latest # or pnpm add @itech-india/itech-fluentui@latest ``` ## Peer Dependencies The following are peer dependencies and must be installed separately: ```bash npm install react@^18.0.0 react-dom@^18.0.0 ``` **Note:** Fluent UI dependencies (`@fluentui/react-components`, `@fluentui/react-icons`) are bundled in the package. ## npm Access (Maintainers) The package is private on npmjs.com, so maintainers must authenticate before publishing: **Option 1: Using npm login (npm private scope)** ```bash npm login --registry=https://registry.npmjs.org # Enter credentials for an org member with publish access ``` **Option 2: Using Auth Token (For CI/CD)** Create an `.npmrc` file in your project root: ``` //registry.npmjs.org/:_authToken=${NPM_TOKEN} @itech-india:registry=https://registry.npmjs.org ``` **Note:** Ensure your npm user is listed as a maintainer: `npm access ls-collaborators @itech-india/itech-fluentui --registry=https://registry.npmjs.org`. --- # Quick Start ## Basic Setup ```tsx // main.tsx or App.tsx import React from "react"; import ReactDOM from "react-dom/client"; import { FluentProvider } from "@fluentui/react-components"; import { iTechLightTheme, iTechDarkTheme } from "@itech-india/itech-fluentui"; import { useState } from "react"; import App from "./App"; function Root() { const [mode, setMode] = useState<"light" | "dark">("light"); const theme = mode === "light" ? iTechLightTheme : iTechDarkTheme; return ( ); } ReactDOM.createRoot(document.getElementById("root")!).render( ); ``` ## Using Components ```tsx import { Button, Input, Card } from "@itech-india/itech-fluentui/components"; import { AddIcon } from "@itech-india/itech-fluentui/components/fluent-icons"; function MyForm() { return ( ); } ``` ## Using Design Tokens ```tsx import { spacing, typography, getBrandColor } from "@itech-india/itech-fluentui"; const styles = { padding: spacing.m, // 12 fontSize: typography.fontSize[400], // 16 color: getBrandColor("vivid_blue", 80), // "#1222fe" }; ``` --- # Design Tokens ## Typography ### Font Sizes ```tsx import { typography, fs } from "@itech-india/itech-fluentui"; // Direct access typography.fontSize[100]; // 10px typography.fontSize[200]; // 12px typography.fontSize[300]; // 14px typography.fontSize[400]; // 16px (base) typography.fontSize[500]; // 20px typography.fontSize[600]; // 24px typography.fontSize[700]; // 28px typography.fontSize[800]; // 32px typography.fontSize[900]; // 40px typography.fontSize[1000]; // 68px // Helper function fs(400); // "16px" ``` ### Font Families ```tsx typography.fontFamily.base; // "Segoe UI, ..." typography.fontFamily.monospace; // "Consolas, ..." typography.fontFamily.numeric; // "Bahnschrift, ..." ``` ### Font Weights ```tsx typography.fontWeight.light; // 300 typography.fontWeight.regular; // 400 typography.fontWeight.medium; // 500 typography.fontWeight.semibold; // 600 typography.fontWeight.bold; // 700 ``` ### Line Heights ```tsx typography.lineHeight[100]; // 14px typography.lineHeight[400]; // 22px typography.lineHeight[700]; // 36px ``` ## Spacing ```tsx import { spacing, sp } from "@itech-india/itech-fluentui"; // Direct access spacing.none; // 0px spacing.xxs; // 2px spacing.xs; // 4px spacing.sNudge; // 6px spacing.s; // 8px spacing.mNudge; // 10px spacing.m; // 12px spacing.l; // 16px spacing.xl; // 20px spacing.xxl; // 24px spacing.xxxl; // 32px // Helper function sp("m"); // "12px" ``` ## Colors ### Brand Colors 4 brand variants, each with 16-step color scales (10-160): ```tsx import { getBrandColor } from "@itech-india/itech-fluentui"; // Available brands: brand_1, irepo, blue, vivid_blue const primary = getBrandColor("vivid_blue", 80); // "#1222fe" const light = getBrandColor("vivid_blue", 160); // "#e4eeff" const dark = getBrandColor("vivid_blue", 10); // "#000016" ``` **Brand Variants:** - `brand_1` - Corporate Blue (#0f6cbd → #ebf3fc) - `irepo` - Purple Brand (#5a07d7 → #e4cdfe) - `blue` - Traditional Blue (#446ed4 → #edf3ff) - `vivid_blue` - Vibrant Blue (#1222fe → #e4eeff) ### Neutral Colors ```tsx import { getNeutralGrey, neutralColors } from "@itech-india/itech-fluentui"; // 50 shades of grey (0-98, increments of 2) const grey = getNeutralGrey(50); // "#808080" const background = getNeutralGrey(96); // "#f5f5f5" const text = getNeutralGrey(20); // "#333333" // Direct access const black = neutralColors.black; // "#000000" const white = neutralColors.white; // "#ffffff" const grey = neutralColors.grey[50]; // "#808080" ``` ### Alpha Colors ```tsx import { alphaColors } from "@itech-india/itech-fluentui"; // White with opacity alphaColors.white[5]; // 5% white alphaColors.white[10]; // 10% white alphaColors.white[20]; // 20% white alphaColors.white[40]; // 40% white alphaColors.white[50]; // 50% white alphaColors.white[60]; // 60% white alphaColors.white[90]; // 90% white // Black with opacity alphaColors.black[5]; // 5% black alphaColors.black[10]; // 10% black alphaColors.black[20]; // 20% black alphaColors.black[40]; // 40% black alphaColors.black[50]; // 50% black alphaColors.black[60]; // 60% black alphaColors.black[90]; // 90% black ``` ### Shared Color Palettes 40+ Microsoft Fluent Design color palettes: ```tsx import { getSharedColor, sharedColors } from "@itech-india/itech-fluentui"; // Helper function const blue = getSharedColor("blue", "primary"); // "#0078d4" const teal = getSharedColor("teal", "tint20"); // "#2aa0a4" const green = getSharedColor("green", "primary"); // "#107c10" // Direct access sharedColors.blue.primary; // "#0078d4" sharedColors.green.tint20; // "#359b35" sharedColors.red.shade10; // "#bc2f32" sharedColors.purple.tint40; // "#c6b1de" ``` **Available Color Palettes:** - **Reds & Oranges:** darkRed, burgundy, cranberry, red, darkOrange, bronze, pumpkin, orange, peach - **Yellows & Golds:** marigold, yellow, gold, brass - **Browns:** brown, darkBrown - **Greens:** lime, forest, seafoam, lightGreen, green, darkGreen - **Teals & Cyans:** lightTeal, teal, darkTeal, cyan - **Blues:** steel, lightBlue, blue, royalBlue, darkBlue, cornflower, navy - **Purples:** lavender, purple, darkPurple, orchid, grape - **Pinks & Magentas:** berry, lilac, pink, hotPink, magenta, plum - **Neutrals:** beige, mink, silver, platinum, anchor, charcoal Each palette includes 12 shades: shade50, shade40, shade30, shade20, shade10, primary, tint10, tint20, tint30, tint40, tint50, tint60 ## Layout Tokens ### Corner Radius ```tsx import { cornerRadius, cr } from "@itech-india/itech-fluentui"; cornerRadius.none; // 0px cornerRadius.small; // 2px cornerRadius.medium; // 4px cornerRadius.large; // 6px cornerRadius.xLarge; // 8px cornerRadius.circular; // 9999px cr("medium"); // "4px" ``` ### Shadows ```tsx import { getShadow } from "@itech-india/itech-fluentui"; getShadow("shadow2"); // Subtle shadow getShadow("shadow4"); // Tooltip shadow getShadow("shadow8"); // Card shadow getShadow("shadow16"); // Dialog shadow getShadow("shadow28"); // Panel shadow getShadow("shadow64"); // Modal shadow ``` ### Card Padding ```tsx import { getCardPadding } from "@itech-india/itech-fluentui"; getCardPadding("small"); // { horizontal: 8, vertical: 8, gap: 8, cornerRadius: 2 } getCardPadding("medium"); // { horizontal: 12, vertical: 12, gap: 12, cornerRadius: 4 } getCardPadding("large"); // { horizontal: 16, vertical: 16, gap: 16, cornerRadius: 6 } ``` --- # Components ## Available Components (85+ Total) ### Layout & Structure - Accordion, Card, Divider, Separator, Tabs, Table, Toolbar, Layout, Header, Sidebar, DataTable, Pagination ### Form Components - Button, FilterButton, Checkbox, Chip, Input, Label, MultiSelect, PasswordInput, PhoneInput, RadioGroup, SearchFilter, Select, Switch, Textarea, Field, Form, Combobox ### Date & Time - Calendar, DatePicker, TimePicker, DateTimePicker, DateRangePicker, DateRangeTimePicker ### Navigation - Breadcrumb, DropdownMenu, Link ### Overlays & Modals - AlertDialog, Dialog, Drawer, Popover, Tooltip ### Feedback & Status - Avatar, Badge, BadgeWrapper, CounterBadge, PresenceBadge, ProgressBar, CircularProgress, Skeleton, Spinner, Loader, Toast, MatchBadge, StatusIndicator ### Cards & Content - CandidateCard, JobMatchCard, FileCard, EmptyState, ViewToggle, SkillMatchIndicator, Timeline, FilterPanel, ExpandableListItem, ColumnSelector, SearchSidebar, AuthLayout ### Product Components - PricingCard, RadioCard, AppCard, CategoryCard, SolutionCard, ProductCard, ResumeCard, HeroSection, SearchHero, SupportCard, FileUploader, DocumentViewer, BillingCard, CreditBalanceCard ### Media - Image, Logo ## Component Usage ```tsx // Import from components subpath import { Button, Input, Card } from "@itech-india/itech-fluentui/components"; // Or from main export import { Button, Input, Card } from "@itech-india/itech-fluentui"; // Icons import { AddIcon, EditIcon, DeleteIcon, } from "@itech-india/itech-fluentui/components/fluent-icons"; ``` --- # Themes ## Available Themes 8 complete themes (4 brands × 2 modes): ```tsx import { iTechLightTheme, iTechDarkTheme, getTheme } from "@itech-india/itech-fluentui"; // Use default theme const theme = iTechLightTheme; // Get theme for specific brand and mode const theme = getTheme("vivid_blue", "dark"); ``` ## Multi-Brand Support ```tsx import { getTheme } from "@itech-india/itech-fluentui"; import { FluentProvider } from "@fluentui/react-components"; function App() { const [brand, setBrand] = useState("vivid_blue"); const [mode, setMode] = useState("light"); const theme = getTheme(brand, mode); return {/* Your app */}; } ``` --- # React Hooks ## useDesign Hook Complete theme and brand management: ```tsx import { useDesign } from "@itech-india/itech-fluentui"; function ThemeSwitcher() { const { brand, mode, setBrand, setMode, toggleMode } = useDesign(); return (
); } ``` ## useThemeMode Hook Theme mode management only: ```tsx import { useThemeMode } from "@itech-india/itech-fluentui"; function DarkModeToggle() { const { mode, toggleMode } = useThemeMode(); return ( ); } ``` ## useITechTheme Hook Get current FluentUI theme object: ```tsx import { useITechTheme } from "@itech-india/itech-fluentui"; function MyComponent() { const theme = useITechTheme(); return (
Themed content
); } ``` --- # Component Development Workflow ## Architecture Overview **Key Principle:** One source of truth. All UI components live in `@itech-india/itech-fluentui`. All apps consume the same package. ## Workflow: Adding New Components from Figma ### Step 1: Analyze Figma Design 1. **Open Figma Design** - Identify the component structure - Note spacing, colors, typography - Check variants (sizes, states, themes) 2. **Extract Design Tokens** (if new tokens needed) ```typescript // Check if tokens exist in src/design-tokens/tokens.ts // If not, add them: export const newTokens = { spacing: { componentPadding: 16, }, colors: { componentBg: "#FFFFFF", }, }; ``` ### Step 2: Create Component File 1. **Create component file** in `src/components/ui/` ```bash # Example: creating a new "notification" component touch src/components/ui/notification.tsx ``` 2. **Component Template:** ```typescript import * as React from "react"; import { makeStyles, tokens, mergeClasses, } from "@fluentui/react-components"; import { cn } from "../../lib/utils"; import { useDesign } from "../../design-tokens/hooks"; // Define component props interface export interface NotificationProps { variant?: "info" | "success" | "warning" | "error"; title?: string; message: string; onClose?: () => void; className?: string; } // Define styles using design tokens const useNotificationStyles = makeStyles({ root: { padding: tokens.spacingHorizontalM, borderRadius: tokens.borderRadiusMedium, // Use design tokens, not hardcoded values }, // ... more styles }); // Component implementation export const Notification = React.forwardRef< HTMLDivElement, NotificationProps >( ( { variant = "info", title, message, onClose, className, ...props }, ref ) => { const { brand, mode } = useDesign(); const styles = useNotificationStyles(); return (
{/* Component JSX */}
); } ); Notification.displayName = "Notification"; ``` ### Step 3: Use Design Tokens **Always use design tokens, never hardcode values:** ```typescript // ✅ GOOD - Uses tokens padding: tokens.spacingHorizontalM, color: tokens.colorNeutralForeground1, borderRadius: tokens.borderRadiusMedium, // ❌ BAD - Hardcoded values padding: "16px", color: "#000000", borderRadius: "4px", ``` ### Step 4: Export Component 1. **Add to `src/components/ui/index.ts`:** ```typescript export * from "./notification"; ``` 2. **Verify export in main `src/index.ts`:** ```typescript // Should already export all from components/ui export * from "./components/ui"; ``` ### Step 5: Test Component Locally ```bash # Build the package npm run build # Link locally (in library directory) npm link # In your test app npm link @itech-india/itech-fluentui # Import and test import { Notification } from "@itech-india/itech-fluentui"; ``` ### Step 6: Build & Publish ```bash # 1. Build npm run build # 2. Update version npm version patch # for bug fixes npm version minor # for new features npm version major # for breaking changes # 3. Publish npm publish --tag latest ``` ### Step 7: Update All Applications In each of your 5+ applications: ```bash # Update to latest version npm update @itech-india/itech-fluentui # Or install specific version npm install @itech-india/itech-fluentui@1.1.0 ``` **All apps automatically get the new component!** 🎉 ## Component Development Best Practices ### 1. Follow Figma Design Exactly (But Stay Theme-Agnostic) - Match spacing, typography, layout from Figma - **Use design tokens for colors** - Never hardcode brand colors - Support all variants shown in Figma - Match interaction states (hover, focus, disabled) - **Remember:** Components should work with ANY brand colors, not just one ### 2. Use TypeScript Strictly ```typescript // ✅ Always define props interface export interface ComponentProps { variant?: "primary" | "secondary"; size?: "small" | "medium" | "large"; children: React.ReactNode; className?: string; } // ✅ Use forwardRef for ref support export const Component = React.forwardRef( ({ variant, size, children, className, ...props }, ref) => { // ... } ); ``` ### 3. Support Theme System (Theme-Agnostic Design) ```typescript import { useDesign } from "../../design-tokens/hooks"; import { tokens } from "@fluentui/react-components"; const Component = () => { const { brand, mode } = useDesign(); // ✅ Component automatically adapts to ANY brand theme // No hardcoded colors - uses tokens that change with brand const styles = makeStyles({ root: { backgroundColor: tokens.colorBrandBackground, // Adapts to brand color: tokens.colorBrandForeground1, // Adapts to brand padding: tokens.spacingHorizontalM, // Stays consistent borderRadius: tokens.borderRadiusMedium, // Stays consistent }, }); }; ``` **Critical Rule:** Components must work with **any brand theme** without modification. Only colors change, not structure. ### 4. Component Checklist Before adding a component to the library: - [ ] Component matches Figma design exactly (structure, spacing, layout) - [ ] **Uses design tokens for ALL colors** (no hardcoded brand colors) - [ ] **Theme-agnostic** - Works with any brand theme without changes - [ ] Supports all variants from Figma - [ ] TypeScript types are complete - [ ] Component is exported in `index.ts` - [ ] Tested locally with `npm link` - [ ] **Tested with multiple brand themes** (verify colors adapt correctly) - [ ] Build succeeds (`npm run build`) - [ ] Documentation added (if needed) - [ ] Accessible (ARIA, keyboard support) - [ ] Theme-aware (works in light/dark modes) - [ ] **No brand-specific logic** - Components adapt via tokens only ## Client Brand Customization ### Key Principle: Components Are Theme-Agnostic **Important:** When providing an app to a client, you only need to change **brand theme colors**. The component UI structure, layout, spacing, and behavior remain unchanged. ### How It Works ``` ┌─────────────────────────────────────────┐ │ @itech-india/itech-fluentui Components │ │ (UI Structure - Never Changes) │ │ - Button layout & spacing │ │ - Input structure & behavior │ │ - Card padding & shadows │ │ - All component logic │ └─────────────────────────────────────────┘ │ │ Uses Design Tokens │ ┌─────────────▼────────────────────────────┐ │ Brand Theme Colors │ │ (Only This Changes Per Client) │ │ - Primary color: #1222fe → #FF5733 │ │ - Secondary colors │ │ - Brand-specific palette │ └─────────────────────────────────────────┘ ``` ### Adding a New Brand Theme for a Client #### Step 1: Add Brand Colors to Tokens ```typescript // src/design-tokens/tokens.ts export const brandPalettes = { // ... existing brands brand_1: { /* ... */ }, irepo: { /* ... */ }, blue: { /* ... */ }, vivid_blue: { /* ... */ }, // Add new client brand client_acme: { 10: "#0a0016", // Darkest 20: "#1a0033", 30: "#2a0047", 40: "#3a0063", 50: "#4a0080", 60: "#5a009e", 70: "#6a00dd", 80: "#FF5733", // Primary brand color (from client) 90: "#FF7A5C", 100: "#FF9D85", 110: "#FFBFAE", 120: "#FFE1D7", 130: "#FFF0EB", 140: "#FFF5F2", 150: "#FFF9F7", 160: "#FFFCFB", // Lightest }, } as const satisfies Record; ``` #### Step 2: Update Types ```typescript // src/design-tokens/types.ts export type BrandVariant = | "brand_1" | "irepo" | "blue" | "vivid_blue" | "client_acme"; // Add new brand ``` #### Step 3: Register Brand Variant ```typescript // src/design-tokens/theme.ts export const brandVariants: Record = { brand_1: createBrandVariants(brandPalettes.brand_1), irepo: createBrandVariants(brandPalettes.irepo), blue: createBrandVariants(brandPalettes.blue), vivid_blue: createBrandVariants(brandPalettes.vivid_blue), client_acme: createBrandVariants(brandPalettes.client_acme), // Add here }; ``` #### Step 4: Use in Client App ```typescript // In client's app (e.g., client-acme-app) import { FluentProvider } from "@fluentui/react-components"; import { getTheme } from "@itech-india/itech-fluentui"; function App() { // Use client-specific brand const theme = getTheme("client_acme", "light"); return ( {/* All components automatically use client_acme colors */} {/* Button structure unchanged, only colors change */} ); } ``` ### What Changes vs. What Stays the Same #### ✅ Changes (Brand Colors Only) - Primary brand color - Secondary brand colors - Brand-specific color palette - Theme colors (light/dark variants) #### ❌ Stays the Same (Component UI) - Component structure and layout - Spacing and padding - Typography sizes and weights - Border radius and shadows - Component behavior and interactions - All component logic --- # Publishing to npm (private) ## Manual Publishing ### Step 1: Create npm Automation Token 1. Visit https://www.npmjs.com/settings/@itech-india/tokens (org admin only) 2. Generate a new **Automation** token (publish + install) 3. Copy the token (starts with `npm_`) and store it securely ### Step 2: Configure npm for npmjs.com ```bash echo \"@itech-india:registry=https://registry.npmjs.org\" >> ~/.npmrc echo \"//registry.npmjs.org/:_authToken=\${NPM_TOKEN}\" >> ~/.npmrc ``` ### Step 3: Build the Package ```bash npm run build ``` This creates a `lib/` folder with compiled JavaScript. ### Step 4: Publish to npmjs.com ```bash npm publish --tag latest ``` > ✅ Once published to npmjs.com, only authenticated users can install `@itech-india/itech-fluentui`. **🎉 Done! Your package is now live for internal consumers!** ## Updating the Package When you make changes: ```bash # Update version (choose one) npm version patch # 1.0.0 -> 1.0.1 (bug fixes) npm version minor # 1.0.0 -> 1.1.0 (new features) npm version major # 1.0.0 -> 2.0.0 (breaking changes) # Build and publish (npmjs.com) npm run build npm publish --tag latest ``` ## Semantic Versioning - **Patch (1.0.0 → 1.0.1)**: Bug fixes, small improvements - **Minor (1.0.0 → 1.1.0)**: New features, new components (backward compatible) - **Major (1.0.0 → 2.0.0)**: Breaking changes --- # GitHub Actions Setup ## Automatic Publishing with GitHub Actions **Yes!** GitHub Actions can publish to **npmjs.com** every time code lands on `main`. ## Quick Setup (5 Minutes) ### Step 1: Create npm Automation Token 1. Visit https://www.npmjs.com/settings/@itech-india/tokens (org admin) 2. Generate an **Automation** token (publish + install rights) 3. Copy the value (`npm_...`) and store it securely ### Step 2: Add Token to GitHub Secrets 1. Go to your GitHub repository: `https://github.com/iTech-India/itech-fluentui` 2. Click **Settings** → **Secrets and variables** → **Actions** 3. Click **"New repository secret"** 4. Name: `NPM_TOKEN` 5. Value: paste the npm automation token 6. Click **"Add secret"** ### Step 3: Workflow Files Verification The workflow files are already created and configured: - `.github/workflows/publish-npm.yml` - Auto-publishes to npmjs.com - `.github/workflows/deploy-storybook.yml` - Deploys Storybook to GitHub Pages - `.github/workflows/ci.yml` - Builds and tests on every push **Repository URL:** Already configured as `https://github.com/iTech-India/itech-fluentui.git` **That's it!** Your workflow is ready. ## How Automatic Publishing Works ### Option 1: Publish on Version Tags (Recommended) ```bash # 1. Make changes and update version npm version patch # or minor/major # This creates a git tag (v1.0.1) # 2. Push code and tag to GitHub git push git push --tags # 3. GitHub Actions automatically: # - Builds the package # - Publishes to npmjs.com # - Verifies publication ``` ### Option 2: Publish on Version Change (Alternative) ```bash # 1. Manually update version in package.json # Edit package.json: "version": "1.0.1" # 2. Commit and push git add package.json git commit -m "Bump version to 1.0.1" git push # 3. GitHub Actions detects version change # - Compares with published version # - Publishes if different ``` ### Workflow Triggers The workflow automatically runs when: 1. **Version tag pushed:** `git push --tags` (after `npm version`) 2. **Push to main/master:** Checks if version changed 3. **Manual trigger:** GitHub Actions UI → "Run workflow" ## Complete Update Workflow Example ```bash # 1. Make changes to your code # Edit src/components/ui/button.tsx # 2. Test locally npm run build npm link # Test in your app # 3. Update CHANGELOG.md # Add entry for new version # 4. Commit changes (if using git) git add . git commit -m "Fix button hover state" git push # 5. Update version npm version patch # Automatically updates package.json and creates git tag # 6. Push tags git push --tags # 7. GitHub Actions automatically publishes! # Check Actions tab to see progress # 8. Verify npm view @itech-india/itech-fluentui # Should show new version ``` --- # Quick Reference ## Quick Command Reference | Action | Command | | ---------------- | ------------------------------------------------------ | | **Login** | `npm login` | | **Build** | `npm run build` | | **Publish** | `npm publish --tag latest` | | **Update Patch** | `npm version patch && npm publish --tag latest` | | **Update Minor** | `npm version minor && npm publish --tag latest` | | **Update Major** | `npm version major && npm publish --tag latest` | | **Install** | `npm install @itech-india/itech-fluentui@latest` | | **View Info** | `npm view @itech-india/itech-fluentui` | ## Design Token Quick Reference ### Typography ```typescript fs(400); // "16px" lh(400); // "22px" typography.fontWeight.semibold; // 600 ``` ### Spacing ```typescript sp("m"); // "12px" spacing.l; // 16 ``` ### Colors ```typescript getBrandColor("vivid_blue", 80); // "#1222fe" getNeutralGrey(50); // "#808080" getSharedColor("blue", "primary"); // "#0078d4" ``` ### Layout ```typescript cr("medium"); // "4px" getShadow("shadow8"); // Shadow CSS value getCardPadding("medium"); // Padding configuration ``` ## Import Quick Reference ### Design Tokens ```typescript import { spacing, typography, colors } from "@itech-india/itech-fluentui"; import { sp, fs, cr, getShadow } from "@itech-india/itech-fluentui"; ``` ### Themes ```typescript import { iTechLightTheme, iTechDarkTheme, getTheme } from "@itech-india/itech-fluentui"; ``` ### Components ```typescript import { Button, Input, Card } from "@itech-india/itech-fluentui/components"; ``` ### Icons ```typescript import { AddIcon, EditIcon, DeleteIcon, } from "@itech-india/itech-fluentui/components/fluent-icons"; ``` ### Hooks ```typescript import { useDesign, useThemeMode } from "@itech-india/itech-fluentui"; ``` --- # Pre-Publish Checklist Use this checklist before publishing to npmjs.com: ## Pre-Publish Steps ### 1. Package Configuration - [ ] Verify `version` in `package.json` is correct - [ ] Verify `name` is `@itech-india/itech-fluentui` - [ ] Verify `publishConfig.registry` is `https://registry.npmjs.org/` - [ ] Update repository URL if needed (currently shows "your-org") ### 2. Build & Verify - [ ] Run `npm run build` - Should complete without errors - [ ] Verify `lib/` directory is created with compiled files - [ ] Verify TypeScript definitions (`.d.ts` files) are generated - [ ] Check for any TypeScript errors: `npx tsc --noEmit` ### 3. Test Locally - [ ] Test installation: `npm link` - [ ] Test in a fresh project (recommended): ```bash npm link cd /path/to/test-project npm link @itech-india/itech-fluentui ``` - [ ] Verify imports work: ```tsx import { Button, spacing, getBrandColor } from "@itech-india/itech-fluentui"; ``` - [ ] Test components render correctly - [ ] Test theme switching works - [ ] Test design tokens are accessible ### 4. Documentation - [ ] README.md is up to date - [ ] CHANGELOG.md is updated with changes - [ ] Documentation is complete ### 5. npmjs.com Authentication - [ ] Logged in to npm: `npm whoami` - [ ] Listed as maintainer: `npm access ls-collaborators @itech-india/itech-fluentui` - [ ] `.npmrc` is configured if using tokens - [ ] GitHub token is valid (if using automation) ### 6. Version Management - [ ] Decide on version bump: - `patch` (1.0.0 → 1.0.1) for bug fixes - `minor` (1.0.0 → 1.1.0) for new features - `major` (1.0.0 → 2.0.0) for breaking changes - [ ] Update version: `npm version patch|minor|major` - [ ] Update CHANGELOG.md ### 7. Final Checks - [ ] Build succeeds without errors - [ ] TypeScript types are correct - [ ] All exports work correctly - [ ] Package structure is correct - [ ] No sensitive data in package (API keys, tokens, etc.) ## Publishing Steps ```bash # 1. Verify build (should already succeed) npm run build # 2. Login to npm (if not already logged in) npm login # 3. Update version (recommended: patch for bug fixes) npm version patch # This will update version and create git tag # 4. Publish npm publish --tag latest # 5. Verify publication npm view @itech-india/itech-fluentui ``` **Note:** The `prepublishOnly` script will automatically run `npm run build` before publishing. ## Post-Publish Checklist After publishing: - [ ] Verify package appears on npmjs.com: https://github.com/iTech-India/itech-fluentui/pkgs/npm/itech-fluentui - [ ] Test installation in a fresh project: ```bash npm install @itech-india/itech-fluentui ``` - [ ] Verify package works correctly - [ ] Update any consuming applications - [ ] Notify team about new version --- # Troubleshooting ## Publishing Issues ### "Package name taken" - Package name `@itech-india/itech-fluentui` might be taken - Change name in `package.json`: `"name": "itech-fluent"` ### "Must be logged in" - Run `npm login` first ### "Build errors" - Check TypeScript errors: `npm run build` - Fix errors before publishing ### "Access denied" - Make sure you're logged in: `npm whoami` - Check package name is available: `npm view @itech-india/itech-fluentui` ## Usage Issues ### TypeScript errors - Make sure you have the latest TypeScript version - Check that all peer dependencies are installed ### Theme not applying - Verify `FluentProvider` is wrapping your app - Check that theme is imported correctly ### GitHub Actions not publishing - Check `NPM_TOKEN` secret is set correctly - Verify token is an npm **Automation** token with publish access - Check workflow logs in Actions tab --- # FAQs ### Do consuming apps need Fluent UI installed? ❌ **No.** Fluent UI is a bundled dependency. All components are re-exported from `@itech-india/itech-fluentui`. ### Do apps need to configure anything? ❌ **No.** Just wrap your app with `FluentProvider` and you're ready to go. ### Are themes auto-applied? ✔ **Yes.** Wrap your app with `FluentProvider` and themes apply automatically. ### How do I customize themes? Edit theme files in the library (`src/design-tokens/theme.ts`) and rebuild. Apps will get updates via package updates. ### Can I use Fluent UI components directly? ✔ **Yes.** All Fluent UI v9 components are re-exported and work with iTech themes. ### Are components tree-shakeable? ✔ **Yes.** Import only what you need: `import { Button } from '@itech-india/itech-fluentui/components'`. ### Does it work with TypeScript? ✔ **Yes.** Full TypeScript support with type definitions included. ### How do I add new design tokens? Add tokens to `src/design-tokens/tokens.ts`, update types in `types.ts`, rebuild. ### How do I update tokens from Figma? Export tokens from Figma → update `src/design-tokens/tokens.ts` → rebuild → publish. ### What if I need a component that's not in the library? 1. Check if Fluent UI has it (it's re-exported) 2. Create custom component in `src/components/ui/` 3. Export from `src/components/ui/index.ts` 4. Follow component development workflow --- **Last Updated:** 2025-11-25 **Package Version:** 1.0.1 **Access:** Private - npmjs.com (restricted) **Made with ❤️ by the iTech Design Team**