Inspira UI
Getting Started

How To Contribute

Follow the following guidelines to ensure the smooth collaboration

Thank you for your interest in contributing to the Inspira UI project! Your contributions help make this project better for everyone. Please take a moment to read through these guidelines to ensure a smooth collaboration.

Table of Contents

  1. Getting Started
  2. Code of Conduct
  3. How to Contribute
  4. Project Structure
  5. Style Guidelines
  6. Documentation Guidelines
  7. Testing
  8. License

Getting Started

  • Fork the Repository: Create a personal fork of the project on GitHub.
  • Clone Your Fork: Clone your forked repository to your local machine.
  • Create a Branch: Create a new branch for your contribution (git checkout -b feature/YourFeatureName).
  • Install Dependencies: Run pnpm install to install all necessary dependencies.

Code of Conduct

By participating in this project, you agree to abide by the Code of Conduct, which aims to foster an open and welcoming environment.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue and include:

  • A clear and descriptive title.
  • Steps to reproduce the issue.
  • Expected and actual results.
  • Screenshots or code snippets, if applicable.

Suggesting Enhancements

We welcome suggestions for new features or improvements. Please open an issue and include:

  • A clear and descriptive title.
  • A detailed description of the enhancement.
  • Any relevant examples or mockups.

Adding New Components

We appreciate contributions that add new components to the library. Please ensure that:

  • The component is generally useful and aligns with the project's goals.
  • The component is compatible with both Nuxt and Vue.
  • You follow the coding and documentation guidelines outlined below.
  • You include unit tests for your component.

Components guidelines

  1. Create or Update index.ts
    Each folder under components/content/inspira/ui/<component-folder-name>/ should have an index.ts that exports all Vue files. For example:
// index.ts
export { default as Book } from "./Book.vue";
export { default as BookDescription } from "./BookDescription.vue";
export { default as BookHeader } from "./BookHeader.vue";
export { default as BookTitle } from "./BookTitle.vue";
  1. Registry Dependencies: If your new component depends on (or uses) other Inspira UI components, you must update the COMPONENT_DEPENDENCIES map in ~/scripts/crawl-content.ts to reflect those relationships. This helps the library understand which components should be installed together when a user adds them via the CLI.
  2. Nuxt-Only Features: If your new component or its example uses Nuxt-only features such as <ClientOnly>, please mention this in the documentation. This ensures users know there may be limitations or additional steps when using the component outside of Nuxt.

This ensures that users can install the component through the CLI and that all dependencies are properly declared.

  1. Avoid External Components: When creating components, avoid using external UI components (like <UiButton> or similar) that are not part of the core Vue.js ecosystem.
  2. Explicit Imports: Even if you're using Nuxt's auto-imports feature during development, always include explicit imports in your component code. This ensures compatibility with Vue.js users who don't have auto-imports. For example:
<script setup lang="ts">
import { useWindowSize } from "@vueuse/core";
import { onMounted, ref } from "vue";
// Include all imports explicitly
</script>
  1. Icon Usage: If you need icons in your demos or components, use the built-in <Icon> component rather than pasting raw SVGs into your templates.

Project Structure

Understanding the project structure is crucial for effective contribution:

  • Components Directory:
    • Main components should be placed in components/content/inspira/ui/<component-folder-name>/.
      • Include an index.ts file to export each component within that folder.
    • Example components should be placed in components/content/inspira/examples/<component-folder-name>/.
  • Documentation:
    • Documentation files are located in the content/2.components/<category>/ directory.
    • After adding a component, write its documentation in this directory.

Style Guidelines

Coding Standards

  • Language: All components should be written in Vue.js with TypeScript support.
  • Styling: Use Tailwind CSS classes for styling whenever possible.
  • Naming Conventions: Use PascalCase for component names and filenames.

Component Format

Your Vue components should adhere to the following structure:

<!-- Template -->
<script lang="ts" setup>
// Your script code goes here
</script>

<!-- Script (if required) -->
<template>
  <!-- Your template code goes here -->
</template>

<!-- Styles (if required) -->
<style scoped>
/* Your styles go here */
</style>

Props typing and code style

Refer to this Vue.js documentation page -> https://vuejs.org/api/sfc-script-setup#type-only-props-emit-declarations

<script lang="ts" setup>
const { msg = "hello", labels = ["one", "two"] } = defineProps<Props>();

// DON'T ⛔️
const props = defineProps({
  whatever: { type: String, required: true },
  optional: { type: String, default: "default" },
});

const props = withDefaults(defineProps<Props>(), { optional: "default" });

// DO ✅
interface Props {
  whatever: string;
  optional?: string;
}

// Or DO ✅ Props destructure (v3.5+)
interface Props {
  msg?: string;
  labels?: string[];
}
</script>

Constants, interfaces, types and variants

For reusability purposes, you can also add an index.ts file at the root of the component folder to export interfaces, constants, and other useful code elements. Keep in mind that developers will copy and paste the component code into their projects, so it should be very easy to customize according to their standards.

Contants have to be CAPS_CAMEL_CASE in order to identify them clearly inside the code. And prefix them. Please never use Enums; use {} as const instead. 😘

// DON'T ⛔️
const Direction = { Top: 'top'} as const
const ComponentNameDirection = { Top: 'top'} as const

// DON'T ⛔️
enum COMPONENT_NAME_DIRECTION_WRONG = { Top = 'top'};

// DO ✅
import type { ObjectValues } from "@/lib/utils";
export const COMPONENT_NAME_DIRECTION = { Top: 'top', Bottom: 'bottom'} as const

//Types and Interfaces should use CamelCase to differentiate them from constants and variables.
export type ComponentNameDirection = ObjectValues<typeof COMPONENT_NAME_DIRECTION>;

interface {
   direction: ComponentNameDirection; //Enforce correct value : 'top' or 'bottom'
}

You can check the PatternBackground component files components/content/inspira/ui/pattern-background for a complete example.

Notes:

  • Use <script lang="ts" setup> for TypeScript and the Composition API.
  • Keep styles scoped to prevent conflicts.
  • Ensure compatibility with both Nuxt and Vue.

Commit Messages

  • Use the Conventional Commits format.
  • Begin with a type (feat, fix, docs, etc.) followed by a short description.
  • Example: feat: add TextHoverEffect component

Documentation Guidelines

Proper documentation is crucial for users to understand and effectively use the components. Follow these guidelines when adding documentation for new components.

Steps to Add a New Component

  1. Create the Component
    • Place the main component in components/content/inspira/ui/<component-folder-name>/.
    • Follow the Component Format specified above.
    • If the component requires examples or demos, add demo components to components/content/inspira/examples/<component-folder-name>/.
  2. Write Documentation
    • Add a new Markdown file in content/2.components/<category>/ for your component's documentation.
    • Use the appropriate template based on whether your component is single-file or multi-file (see below).
    • Add utility classes section if applicable to your component.
    • Mention the Credits and source if the component is ported from any other UI library or taken inspiration from any other source.
  3. Ensure Compatibility
    • Test your component in both Nuxt and Vue environments.

Single-File Components

For components that are contained within a single .vue file, use the following template:

  1. Front Matter

Begin with YAML front matter that includes the title and description:

---
title: Your Component Title
description: A brief description of what your component does.
---
  1. Preview Section

Use the ComponentLoader to display a live preview of the component. The id should be set to the folder name of your component in components/content/inspira/examples/. In case, there is no folder, then id is not required.

::ComponentLoader{label="Preview" componentName="YourComponentDemo" type="examples" id="your-component-folder-name"}
::
  1. Alerts

If your component has special requirements or dependencies, add an alert section before the installation instructions:

::alert{type="info"}
**Note:** This component requires `package-name` as a dependency.
::

::alert{type="warning"}
**Note:** This component uses the `nuxt-only` syntax with the `<ClientOnly>`. If you are not using Nuxt, you can simply remove it.
::
  1. Installation

Include both CLI and manual installation instructions. If additional setup is required (e.g., dependencies, Tailwind config updates), use a stepper to list all needed steps.

## Install using CLI

::InstallationCli{componentId="your-component-folder-name"}
::

## Install Manually

Copy and paste the following code

::CodeViewer{filename="YourComponent.vue" language="vue" componentName="YourComponent" type="ui" id="your-component-folder-name"}
::
  1. API Documentation

Provide a table listing all props:

## API

| Prop Name | Type      | Default | Description                    |
| --------- | --------- | ------- | ------------------------------ |
| `prop1`   | `string`  | `''`    | Description of prop1.          |
| `prop2`   | `number`  | `0`     | Description of prop2.          |
| `prop2`   | `?number` | `0`     | Description of prop2 optional. |

Example:

---
title: Text Hover Effect
description: A text hover effect that animates and outlines gradient on hover, as seen on x.ai
---

::ComponentLoader{label="Preview" componentName="TextHoverEffectDemo" type="examples"}
::

::alert{type="warning"}
This component uses the `nuxt-only` syntax with the `<ClientOnly>`. If you are not using Nuxt, you can simply remove it.
::

## Install using CLI

::InstallationCli{componentId="text-hover-effect"}
::

## Install Manually

Copy and paste the following code

::CodeViewer{filename="TextHoverEffect.vue" language="vue" componentName="TextHoverEffect" type="ui" id="text-hover-effect"}
::

## API

| Prop Name     | Type     | Default  | Description                                               |
| ------------- | -------- | -------- | --------------------------------------------------------- |
| `text`        | `string` | Required | The text to be displayed with the hover effect.           |
| `duration`    | `number` | `200`    | The duration of the mask transition animation in seconds. |
| `strokeWidth` | `number` | `0.75`   | The width of the text stroke.                             |
| `opacity`     | `number` | `null`   | The opacity of the text.                                  |

In this example, the id used in both ComponentLoader, CodeViewer and InstallationCli is text-hover-effect, which matches the folder name where the component and its demo are stored.

Multi-File Components

For components that consist of multiple files, such as a main component and several sub-components or variants, use the following template:

  1. Front Matter

Begin with YAML front matter:

---
title: Your Components Group Title
description: A brief description of what this group of components does.
---
  1. Preview Sections

Include multiple ComponentLoader sections for each example or variant. The id should be set to the folder name of your component in components/content/inspira/examples/.

::ComponentLoader{label="Preview" componentName="ComponentVariantDemo" type="examples" id="your-component-folder-name"}
::
  1. Alerts

If your component has special requirements or dependencies, add an alert section before the installation instructions:

::alert{type="info"}
**Note:** This component requires `package-name` as a dependency.
::

::alert{type="warning"}
**Note:** This component uses the `nuxt-only` syntax with the `<ClientOnly>`. If you are not using Nuxt, you can simply remove it.
::
  1. Installation

Include both CLI and manual installation instructions. If additional setup is required (e.g., dependencies, Tailwind config updates), use a stepper to list all needed steps.

## Install using CLI

::InstallationCli{componentId="your-component-folder-name"}
::

## Install Manually

Copy and paste the following code in the same folder

::code-group

:CodeViewerTab{label="YourComponent.vue" language="vue" componentName="YourComponent" type="ui" id="your-component-folder-name"}
:CodeViewerTab{filename="YourComponent2.vue" language="vue" componentName="YourComponent2" type="ui" id="your-component-folder-name"}

::
  1. API Documentation

Provide comprehensive API documentation covering all components:

## API

| Prop Name | Type     | Default | Description                             |
| --------- | -------- | ------- | --------------------------------------- |
| `prop1`   | `string` | `''`    | Description applicable to all variants. |

Example:

---
title: Pattern Background
description: Simple animated pattern background to make your sections stand out.
---

Grid background with dot
::ComponentLoader{label="Preview" componentName="PatternBackgroundDotDemo" type="examples" id="pattern-background"}
::

## Install using CLI

::InstallationCli{componentId="pattern-background"}
::

## Install Manually

Copy and paste the following code in the same folder

::code-group

:CodeViewerTab{label="PatternBackground.vue" language="vue" componentName="PatternBackground" type="ui" id="pattern-background"}
:CodeViewerTab{filename="index.ts" language="typescript" componentName="index" type="ui" id="pattern-background" extension="ts"}

::

## Examples

Grid background with big dot and ellipse on top
::ComponentLoader{label="Preview" componentName="PatternBackgroundBigDotDemo" type="examples" id="pattern-background"}
::

Grid background without animation
::ComponentLoader{label="Preview" componentName="PatternBackgroundGridDemo" type="examples" id="pattern-background"}
::

Small grid background with animation
::ComponentLoader{label="Preview" componentName="PatternBackgroundGridSmallDemo" type="examples" id="pattern-background"}
::

## API

| Prop Name   | Type                                                                                                   | Default   | Description                                                                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `animate`   | `boolean`                                                                                              | `false`   | Set `true` if you want to animate the background.                                                                                                              |
| `direction` | `top` \| `bottom` \| `left` \| `right` \| `top-left` \| `top-right` \| `bottom-left` \| `bottom-right` | `top`     | Direction of the animation movement. You can use the const `PATTERN_BACKGROUND_DIRECTION.`                                                                     |
| `direction` | `grid` \| `dot`                                                                                        | `grid`    | Type of pattern. You can use the const `PATTERN_BACKGROUND_VARIANT.`                                                                                           |
| `size`      | `xs` \| `sm` \| `md` \| `lg`                                                                           | `md`      | Size of the background pattern.                                                                                                                                |
| `mask`      | `ellipse` \| `ellipse-top`                                                                             | `ellipse` | Add a mask over the background pattern. You can use the const `PATTERN_BACKGROUND_MASK.`                                                                       |
| `speed`     | `number`                                                                                               | `10000`   | Duration of the animation in `ms`, the bigger it is, the slower the animation. (`20000` slower than `5000`). You can use the const `PATTERN_BACKGROUND_SPEED.` |

### Custom variants, values and constants

You can customize your needs directly within the `index.ts` file. See code below.

## Credits

- Inspired by [Magic UI's Dot Pattern](https://magicui.design/docs/components/dot-pattern) component.
- Inspired by [Magic UI's Grid Pattern](https://magicui.design/docs/components/grid-pattern) component.
- Inspired by [Magic UI's Animated Grid Pattern](https://magicui.design/docs/components/animated-grid-pattern) component.
- Credits to [Nathan De Pachtere](https://nathandepachtere.com/) for porting this component.

Testing

  • Unit Tests: Write unit tests for your component if applicable.
  • Cross-Environment Testing: Ensure that your component works correctly in both Nuxt and Vue environments.
  • Visual Testing: Check the component visually to ensure it renders correctly.
  • CLI Installation Testing: After updating the registry with pnpm build:registry, test the component installation in a separate project by referencing the local registry URL. For example: 
    npx shadcn-vue@latest add "https://localhost:3000/r/<component-name>"

Additional Notes

  • Component Names: Use PascalCase for component filenames and names.
  • IDs: In CodeViewer, CodeViewerTab, and ComponentLoader, the id parameter should be set to the folder name where the component is stored in components/content/inspira/ui/<component-folder-name>/ and components/content/inspira/examples/<component-folder-name>/. This helps in correctly linking the code and examples in the documentation.
  • Demo Components: For each component, create a corresponding Demo component used in the ComponentLoader for previews, and place it in components/content/inspira/examples/<component-folder-name>/.
  • Localization: If your component supports multiple languages, include details in the documentation.

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Installation

How to install Inspira UI in your app.

Code of Conduct

Code of Conduct outlines our expectation for participant behavior as well as consequences for unacceptable conduct.