Sustaina - Shared UI

📦 Installation

To use @sustaina/shared-ui in your project, follow these steps carefully.

Install UI package and required dependencies

Make sure you've installed TailwindCSS and shadcn/ui before installing our library. Don’t skip this.

1. Place shadcn/ui styles

@import "tailwindcss";
@import "tw-animate-css";
@custom-variant dark (&:is(.dark *));

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --chart-1: oklch(0.646 0.222 41.116);
  --chart-2: oklch(0.6 0.118 184.704);
  --chart-3: oklch(0.398 0.07 227.392);
  --chart-4: oklch(0.828 0.189 84.429);
  --chart-5: oklch(0.769 0.188 70.08);
  --radius: 0.625rem;
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.708 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.145 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.145 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.396 0.141 25.723);
  --destructive-foreground: oklch(0.637 0.237 25.331);
  --border: oklch(0.269 0 0);
  --input: oklch(0.269 0 0);
  --ring: oklch(0.439 0 0);
  --chart-1: oklch(0.488 0.243 264.376);
  --chart-2: oklch(0.696 0.17 162.48);
  --chart-3: oklch(0.769 0.188 70.08);
  --chart-4: oklch(0.627 0.265 303.9);
  --chart-5: oklch(0.645 0.246 16.439);
  --sidebar: oklch(0.205 0 0);
  --sidebar-foreground: oklch(0.985 0 0);
  --sidebar-primary: oklch(0.488 0.243 264.376);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.269 0 0);
  --sidebar-accent-foreground: oklch(0.985 0 0);
  --sidebar-border: oklch(0.269 0 0);
  --sidebar-ring: oklch(0.439 0 0);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-ring: var(--sidebar-ring);
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

2. Install library

npm install @sustaina/shared-ui

Peer Dependencies

You must manually install these peer dependencies in your host project:

npm install react react-dom react-hook-form

Supported versions:

{
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0",
    "react-hook-form": "^7.61.1"
  }
}

⚠️ If your project doesn't match the version ranges above, you may get runtime or type errors.

3. Add @sustaina/shared-ui to your CSS

To make styling work with our components, add this to your index.css or root CSS file:

... omit code
@import "@sustaina/shared-ui/styles.css"; /* this include styles/theme.css already */
@source "../../node_modules/@sustaina/shared-ui/dist"; /* depend your root CSS file locate. */
... omit code

Usage

Import @sustaina/shared-ui components within your React component files:

import { Button } from "@sustaina/shared-ui";

export default function MyComponent() {
  return <Button color="primary">Click me!</Button>;
}

Developer Notes

Git Flow

How to developed

We follow a feature/xxx → dev → prod workflow:

• Developed on feature/xxx or bugfix/xxx or any what you want. Then merge request to dev
• Only prod branch triggers npm package publishing.
• To publish a new version:
  • Create a merge request from dev to prod, or
  • Contact your lead developer or maintainer to perform the merge.

Versioning & Commits

We use semantic versioning:

• patch → bug fixes (fix: description)
• minor → new features (feat: description)
• All other commit types (e.g., docs, chore, refactor) do not trigger a version change.

no major change for now just use patch and minor

CSS and Custom Styling

• Prefer Tailwind classes inline whenever possible.

  • If additional CSS is needed, include it in your components.
  • Important: After running npm run build, always check dist/index.css to ensure your custom styles are included in the final build.

• Use styles/theme.css for global customizations:

  • Store custom shorthand colors, CSS variables, or utility classes here.
  • These styles will be available to consumers when they import the library Go check step 3.
  • Example:

    @theme {
      --color-sus-primary-1: #000;
    }

  • Reference: Tailwind Theme Variable Namespaces

Including External Files in the Build

• Add your files to copy-files-to-dist.js:

  • This script handles copying files into the dist folder during the build process.
  • Example entry:

    const filesToCopy = [
      {
        from: "./src/styles/theme.css",
        to: "./dist/index.css",
        mode: "prepend" // "replace" | "append" | "prepend"
      }
    ];

• How mode works:

  • "replace" → overwrite the destination file completely.
  • "append" → add content at the end of the destination file.
  • "prepend" → add content at the beginning of the destination file.

• This script handles copying files into the dist folder during the build process.

• After copying files, you can export them for consumers.

  • Add exports your file in package.json

  "exports": {
    ".": {
      "require": "./dist/index.js",
      "import": "./dist/index.mjs",
      "types": "./dist/index.d.ts"
    },
    "./styles.css": "./dist/index.css",
    "./helpers": "./dist/helpers.js"
  }

• Note: This will happen automatically when you run npm run build.