Netra AI

Use this skill to build or update UI using Netra AI Design System without drifting away from the design system. Start from the local component catalog and repository rules before proposing new patterns.

Quick Start

1. Read references/netra-ai.instructions.md for repository structure, package layout, imports, and Netra-specific usage guidance.
2. Read references/repository-guidelines.md for package boundaries, imports, and design-system rules to be followed while generating UI pages.
3. Read references/typescript-guidelines.md for repository TypeScript, React and Next.js expectations.
4. Read references/governance.md when generating UI pages with Netra AI components. These include mandatory rules for styling, typography, and component usage.
5. Use references/componentCatalog.json to find candidate components before inventing new UI.
6. Read references/turbo-repo-setup.md for Turbo repo installation and references/non-turbo-nextjs-setup.md for standalone Next.js onboarding.
7. Read references/themes.md when the request involves theme selection, theme switching, or applying Netra theme classes.
8. Prefer existing components, Netra tokens, and established import paths.

Onboarding and Installation

Use the setup guide that matches your project type:

• Turbo repo: references/turbo-repo-setup.md
• Standalone Next.js / non-Turbo: references/non-turbo-nextjs-setup.md
• Theme usage: references/themes.md

1. Configure NPM Registry

Create a .npmrc file in your project root and add:

registry=https://centraluhg.jfrog.io/artifactory/api/npm/<artifactory-id>-npm-vir
//centraluhg.jfrog.io/artifactory/api/npm/<artifactory-id>-npm-vir/:_authToken=${AUTH_KEY}

If you are setting up the monorepo for the first time, you need to supply the JFrog Artifactory registry details yourself. Codex and Claude cannot infer the correct registry ID automatically. Use the format above and replace <artifactory-id> with your actual JFrog Artifactory ID.

Use your team's secret-management flow to populate AUTH_KEY instead of committing a real token.

Do not commit .npmrc files that contain real tokens. Prefer environment variables and your team's standard secret management approach.

2. Install Netra AI Packages

npm install @uhg-netra-ai/core-react-components @uhg-netra-ai/common-react-components

Optional icons:

npm install @uhg-netra-ai/netra-ai-icons

Choose the Right Package

• Use core-react-components for foundational shadcn-style building blocks.
• Use common-react-components for richer product patterns and composite components.
• Do not add barrel imports. Keep imports direct and package-specific.

Work With the Component Catalog

Use references/componentCatalog.json as the bundled component catalog for this skill. It contains:

• component name
• description
• direct import path
• primary usage example
• usageExamples array for one or more generation-ready examples
• props metadata
• package classification

Use the catalog to:

• match user requests to existing components
• copy the exact import path
• reuse prop names and example usage
• identify whether a component belongs to core or common

Catalog-First Requirement

• For any component recommendation, always use references/componentCatalog.json as the primary source of truth.
• Do not recommend components based on general React knowledge or inference when the catalog contains a matching Netra component.
• When the user asks which component to use, first identify the best match from the catalog by component name, description, props, and usage examples.
• Prefer the most specific matching component from the catalog over lower-level primitives.
• Only suggest lower-level primitives if the catalog does not contain a dedicated component for that use case.
• If multiple catalog components could fit, recommend the most purpose-built one first and briefly mention the others as alternatives.
• If the catalog is ambiguous or missing a clear match, say that explicitly instead of guessing.

Core Instruction

• Generate code using Netra AI components first, not raw HTML equivalents.
• Before implementing custom behavior, check whether the needed functionality already exists through documented props in references/componentCatalog.json.
• Reuse existing component props, variants, and patterns before adding new logic or wrappers.
• Only implement new functionality when the component catalog and current component APIs do not already support the requirement.
• When new functionality is still needed, keep it minimal and make it fit existing Netra conventions.

Implementation Rules

• Reuse existing Netra components before creating new ones.
• Use Netra color tokens only.
• When using token classes, prefix them by usage:
  • background tokens must use the bg- prefix, for example bg-page-bg
  • text tokens must use the text- prefix, for example text-text-muted
  • icon color tokens must also use the text- prefix, for example text-icon-error
• Text and background tokens cannot be used interchangeably. For example, do not use text-muted as a background color or bg-neutral as a text color.
• For table requests, always prefer Netra common TanStack table components instead of building tables from scratch:
  • use TanStackExpandableTable when rows need expansion
  • use TanStackFilterTable when filtering is needed without expandable rows
  • use TanStackBasicTable when a basic table is needed without filters or expandable rows
• These common TanStack table components already support sorting and pagination, so do not re-implement those features manually unless the existing component cannot satisfy the requirement.
• Prefer lucide-react for icons unless a Netra-specific icon is required.
• Use cn for class merging.
• Follow nearby file naming, stories, tests, and component patterns.
• Keep private helper subcomponents inside the owning file when they are not public API.

Storybook and App Governance

Follow references/governance.md strictly when generating UI pages. Adhering to these rules is essential for maintaining consistency, usability, and compatibility across the Netra AI design system. When generating code for UI pages:

• Do not use raw Tailwind color classes outside the approved token-based patterns.
• Use token classes with the correct semantic prefix. For example:
  • className="text-icon-error"
  • className="bg-page-bg"
• Do not use inline styles except for the explicitly allowed positioning and sizing properties.
• Do not use custom CSS classes for component styling in stories or app examples.
• Do not add custom font sizes or custom font weights to h1 through h6.
• When a Netra component exists for a native HTML element, use the Netra component instead of raw HTML.
• Treat governance rules as mandatory, not optional suggestions.

If No Existing Component Fits

1. Check whether the need is a styled primitive or a higher-level composed pattern.
2. Put foundational primitives in core-react-components.
3. Put composite or product-focused patterns in common-react-components.
4. Keep the API aligned with existing Netra naming and variant patterns.
5. Add or update tests and stories when the repository workflow expects them.

Local Testing

To test this skill locally before committing:

1. Copy or symlink this skill folder into ~/.codex/skills/netra-ai if you want Codex to auto-discover it.
2. Restart Codex after installing or updating the skill.
3. Ask Codex for a task that should trigger the skill, for example:
   • "Use Netra AI to build a contact form with name, email, message fields and a send button with loading state."
   • "Use Netra AI to build a Card with TanStack Table and view all button in card header that opens a Sheet with the full table and additional filters. following repository governance."
4. Check whether the response:
   • chooses components from the catalog
   • uses the exact direct import paths
   • follows token and governance rules strictly
   • prefers core vs common correctly

If you do not want to install it globally yet, keep editing it in the repo and copy it to ~/.codex/skills only for test runs.

References

• references/netra-ai.instructions.md
• references/repository-guidelines.md
• references/typescript-guidelines.md
• references/governance.md
• references/componentCatalog.json
• references/turbo-repo-setup.md
• references/non-turbo-nextjs-setup.md
• references/themes.md