Customization

Core Principles of Customization

The design-tokens.json file is the single source of truth for typography and colors in the project, ensuring consistency across the application.

• tailwind.config.js: Uses design-tokens.json to keep typography settings consistent with Naive UI. It is also used to add and customize utility classes in Tailwind CSS, providing additional styling flexibility.
• store/theme.ts: Overrides Naive UI’s theme based on design-tokens.json, creates global CSS variables for easier use, and manages UI logic such as RTL support, transitions, and sidebar collapse functionality.
• theme/index.ts: Contains the remaining customization parameters beyond typography and colors, allowing you to adjust other aspects of the application’s theme.

In summary, design-tokens.json provides the foundational typography and color settings, while other customization options are available in theme/index.ts. Both tailwind.config.js and store/theme.ts leverage design-tokens.json to apply consistent design tokens throughout the application and offer avenues to customize utility classes and UI behavior.

Integration with Figma

You have the option to modify design tokens either directly in Figma or by editing the design-tokens.json file. The scripts/tokens-tool.js script ensures synchronization between figma-tokens.json (compatible with Figma) and design-tokens.json (compatible with Pinx).

• If customizing from Figma: After generating figma-tokens.json from Figma, use scripts/tokens-tool.js to create the updated design-tokens.json.
• If modifying design-tokens.json directly: Use scripts/tokens-tool.js to update figma-tokens.json to reflect the changes in Figma.

In summary, scripts/tokens-tool.js keeps the Figma and Pinx environments synchronized.

Here you will learn how to use the script tokens-tool

How to Customize Pinx

Customization of Pinx can be achieved through:

• Modifying design-tokens.json directly or via scripts/tokens-tool.js if starting from Figma. This file contains preferences for colors, typography, and border radius.
• Customizing Tailwind CSS in tailwind.config.js to adjust or add utility classes.
• Adjusting template flags and other customization parameters in theme/index.ts to modify settings like layout type (vertical or horizontal), color palette (dark or light mode), router transition types, and more. These settings are documented within their respective files.

Customizing Vue Components

To achieve consistent styling in your Vue components, you have several options:

• Use global CSS variables: Apply styles using variables like var(--fg-secondary-color) directly in your Vue files or external CSS/SCSS files. This ensures consistent theming across your components.
• Use Tailwind CSS utility classes: Apply predefined classes such as text-secondary directly in your templates to style elements quickly and consistently.
• Access theme tokens from store/theme.ts: When you need to pass specific colors or styles as props to components, you can retrieve them using:

const fgSecondaryColor = computed(() => useThemeStore().style['fg-secondary-color']);

If additional CSS variables are needed, you can add them by editing the getCssVars function in theme/index.ts file.

Summary

• To modify typography and colors: Edit the design-tokens.json file.
• To customize Tailwind CSS: Edit the tailwind.config.js file to add or customize utility classes.
• To adjust template flags and other settings: Modify the state in theme/index.ts.
• To use tokens in styles:
  • Use CSS variables: var(--fg-secondary-color)
  • Use utility classes: text-secondary
  • Access from store/theme.ts:
    

const fgSecondaryColor = computed(() => useThemeStore().style['fg-secondary-color']);