@ncino/styles

nCino's shared web component styling package implementing the Gator Design System. Provides CSS design tokens, global styles, and a comprehensive Material-UI theme configuration with TypeScript support for custom component props.

Contributing

For guidance on adding or modifying MUI component overrides, see the Developing MUI Overrides wiki page.

Installation

npm install @ncino/styles
# or
pnpm add @ncino/styles

Quick Start

// app/layout.tsx (or _app.tsx)
import '@ncino/styles/gator';  // Global styles
import { ThemeProvider } from '@mui/material/styles';
import { gatorMUITheme } from '@ncino/styles/gator/themes/MUIGatorTheme';

export default function RootLayout({ children }) {
  return (
    <ThemeProvider theme={gatorMUITheme}>
      {children}
    </ThemeProvider>
  );
}

That's it! All MUI components now use the Gator theme, and TypeScript recognizes custom props like color="ai" automatically.

What's Included

• Design Tokens: Primitive and semantic CSS custom properties
• Global Styles: CSS utilities, grid system, typography classes
• MUI Theme: Complete Material-UI theme with component overrides
• TypeScript Support: Type augmentations for custom MUI props
• Web Fonts: Self-hosted Open Sans variable font

Usage

Using MUI Components

Material-UI components automatically use the Gator theme:

import { Button, TextField, Card, Chip } from '@mui/material';

<Button color="primary">Primary</Button>
<Button color="ai">AI</Button>           {/* Custom Gator color */}
<Button color="neutral">Neutral</Button> {/* Custom Gator color */}

<Chip color="ai" label="AI Feature" />   {/* Custom Gator color */}

Using Design Tokens

Design tokens are available as CSS custom properties:

.my-component {
  /* Colors */
  color: var(--color-text-primary);
  background-color: var(--color-surface-brand);

  /* Spacing (0-18 scale) */
  padding: var(--spacing-8);    /* 16px */
  margin: var(--spacing-10);    /* 24px */
  gap: var(--spacing-5);        /* 8px */

  /* Typography */
  font-size: var(--font-size-body-1);
  font-weight: var(--font-weight-semi-bold);

  /* Other */
  border-radius: var(--border-radius-medium);
  box-shadow: var(--shadow-2-card-raised);
}

Grid System

<div class="gator-container">
  <div class="gator-row">
    <div class="gator-col-12 gator-col-md-6 gator-col-lg-4">
      Column 1
    </div>
    <div class="gator-col-12 gator-col-md-6 gator-col-lg-4">
      Column 2
    </div>
    <div class="gator-col-12 gator-col-md-6 gator-col-lg-4">
      Column 3
    </div>
  </div>
</div>

Individual Token Imports

Import specific token sets if needed:

import '@ncino/styles/gator/tokens/primitive';  // Base colors, font sizes
import '@ncino/styles/gator/tokens/semantic';   // Contextual tokens

TypeScript Setup

How It Works

TypeScript module augmentations are loaded project-wide when you import the theme. You only need to import it once (typically in your app root), and all files get the custom prop types automatically.

Troubleshooting

Custom props showing TypeScript errors

Most Common Cause: Dependency version mismatch in monorepos.

TypeScript creates separate @mui/material instances for different React/@types/react versions. Augmentations only apply when versions match.

Solution: Ensure consistent versions:

{
  "dependencies": {
    "react": "19.2.4",
    "react-dom": "19.2.4"
  },
  "devDependencies": {
    "@types/react": "^19",
    "@types/react-dom": "^19"
  }
}

After updating:

1. Run pnpm install
2. Restart TypeScript server (VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server")
3. Clear caches: rm -rf .next node_modules/.cache

Still not working?

• Verify theme import: Make sure you're importing gatorMUITheme somewhere in your app
• Check installation: Verify node_modules/@ncino/styles exists
• IDE restart: Sometimes a full IDE restart is needed

Exports

Available import paths:

import '@ncino/styles';                                    // Load augmentations
import { gatorMUITheme } from '@ncino/styles';            // Theme (default export)
import '@ncino/styles/gator';                              // Global styles CSS
import { gatorMUITheme } from '@ncino/styles/gator/themes/MUIGatorTheme';
import '@ncino/styles/gator/tokens/primitive';            // Primitive tokens CSS
import '@ncino/styles/gator/tokens/semantic';             // Semantic tokens CSS