mindtickle-ui（头脑痒痒用户界面）

Mindtickle UI

Mindtickle UI is a shadcn-compatible registry built on Tailwind CSS v4 and Base UI primitives. Use it to install source components into consumer projects with npx shadcn@latest add @mindtickle/<name>.

IMPORTANT: Prefer the consumer project's package runner for shadcn commands. Examples below use npx shadcn@latest, but swap in pnpm dlx or bunx when the project uses pnpm or bun or npm or yarn.

Current Project Context

!`npx shadcn@latest info --json 2>/dev/null || echo '{"error": "No shadcn project found. Run shadcn init first."}'`

The project context tells you the actual aliases, installed components, primitive base (base vs radix), icon library, package manager, and resolved file-system paths. Use it before giving setup or import advice.

Setup

1. If components.json is missing, initialize shadcn in Base UI mode:

npx shadcn@latest init --base base

1. Add the Mindtickle registry to components.json:

{
  "registries": {
    "@mindtickle": "https://ui.mindtickle.design/registry/r/{name}.json"
  }
}

1. Install the theme and utility helpers:

npx shadcn@latest add @mindtickle/theme @mindtickle/utils

For a full install, use:

npx shadcn@latest add @mindtickle/all

Principles

1. Use existing Mindtickle components before writing custom markup.
2. Follow Base UI composition rules. Mindtickle is not Radix-first.
3. Use semantic tokens and variants before custom classes.
4. Use local reference files before guessing component APIs.

Critical Rules

Base UI Patterns → rules/base-ui.md

• Use render, not asChild, for Base UI triggers.
• Add nativeButton={false} when render targets are not buttons.
• Select requires items; Slider single values use scalars.
• Controlled ToggleGroup single values wrap and unwrap arrays.

Styling → rules/styling.md

• Use semantic classes and built-in variants.
• Use *-muted surface tokens for subtle backgrounds and hover states.
• Use gap-*, size-*, and cn(); avoid raw colors and manual dark-mode overrides.

Forms → rules/forms.md

• Use FieldGroup + Field for structured forms.
• Use InputGroupInput and InputGroupTextarea inside InputGroup.
• Validation uses data-invalid on the wrapper and aria-invalid on the control.

Icons → rules/icons.md

• Use Icon for Mindtickle's product icon system.
• Use data-icon for inline component icons.
• Do not add icon sizing classes inside shared components.

Composition → rules/composition.md

• Prefer MainNav, GlobalHeader, and PageHeader before custom layouts.
• Group items inside their Group component.
• Overlays need titles; loading buttons are composed with Spinner.

Workflow

1. Refresh project context with npx shadcn@latest info when needed.
2. Check installed components from the injected context or the resolved UI path.
3. Search the Mindtickle registry: npx shadcn@latest search @mindtickle -q "sidebar"
4. Get docs and example URLs: npx shadcn@latest docs <component>
5. Preview before installing: npx shadcn@latest add @mindtickle/<name> --dry-run
6. Install: npx shadcn@latest add @mindtickle/<name>
7. Compare local customizations with upstream updates: npx shadcn@latest add @mindtickle/<name> --diff

Migration Workflow

For existing shadcn/ui projects, migrate incrementally instead of replacing everything at once:

1. Inspect the current setup with npx shadcn@latest info
2. Add the @mindtickle registry and install @mindtickle/theme plus @mindtickle/utils
3. Pick one component or block to migrate at a time
4. Preview the incoming registry item with npx shadcn@latest add @mindtickle/<name> --dry-run
5. Review exact changes with --view and --diff
6. Merge carefully so local customizations are preserved

Use this especially when teams already have local shadcn component edits they do not want to overwrite.

Component Selection

Registry Snapshot

The current registry contains 58 UI components and 3 flagship layout blocks surfaced by this skill.

Local References

These reference files are generated from the same MDX docs that power the docs site, then processed for LLM-friendly local reading:

• accordion
• alert
• alert-dialog
• assisted-input
• avatar
• badge
• breadcrumb
• button
• card
• checkbox
• collapsible
• context-menu
• dialog
• drawer
• dropdown-menu
• empty
• field
• global-header
• hover-card
• icon
• input
• input-group
• kbd
• label
• main-nav
• menubar
• page-header
• pagination
• popover
• progress
• radio-group
• resizable
• scroll-area
• select
• separator
• sheet
• shimmering-text
• skeleton
• slider
• spinner
• switch
• table
• tabs
• textarea
• toast
• toggle
• toggle-group
• tooltip

Local Examples

Start from these examples when you need production-flavored layout patterns:

• main-nav-learner.tsx
• page-header-module.tsx
• global-header-demo.tsx
• field-demo.tsx
• input-group-validation.tsx
• dialog-settings.tsx
• icon-colors.tsx
• assisted-input-demo.tsx

Quick Commands

# Search the Mindtickle registry
npx shadcn@latest search @mindtickle -q "navigation"

# Preview a component without writing files
npx shadcn@latest add @mindtickle/main-nav --dry-run

# Install all Mindtickle UI components and blocks
npx shadcn@latest add @mindtickle/all

# Install a Mindtickle block
npx shadcn@latest add @mindtickle/page-header