Using the Component Library

This guide explains how to integrate and use the Altersquare Vue Component Library in your Vue 3 projects.

Overview

The Altersquare Component Library is a copy-paste component library. This means:

• Components are copied directly into your project
• You have full control over customization
• No external package dependencies for components
• Easy to modify and extend

Installation Methods

Method 1: Copy-Paste (Recommended)

This is the primary way to use components from the library.

Step 1: Browse the Component Documentation

Visit the Components section to find the component you need. Each component page includes:

• Overview and description
• API Reference (props, events, slots)
• Code tab with full source code
• Examples and demos

Step 2: Copy the Component Code

1. Navigate to the component's documentation page
2. Click on the Code tab
3. Copy the entire component file content (template, script, and style sections)
4. Ensure you copy everything including all imports and styles

Step 3: Create Component File in Your Project

1. Create a new file in src/components/sharedComponents/ folder
2. Name it exactly as shown in the documentation (e.g., OInput.vue, OButton.vue)
3. Paste the copied code into the file
4. Save the file

Step 4: Modify Component According to Your Project Design Pattern

Important: Before using the component, modify it to match your project's design patterns and styling:

1. Update styles - Adjust colors, spacing, typography, and other design tokens to match your project's design system
2. Update SCSS variables - Replace any hardcoded values with your project's SCSS variables
3. Adjust component structure - Modify the template structure if needed to match your project's patterns
4. Update class names - Ensure class naming follows your project's conventions
5. Review imports - Check that all imports are correct and match your project structure

This ensures the component integrates seamlessly with your project's design and code style.

Step 5: Import and Use

Import the component in your Vue files and use it in your templates. Check individual component documentation for usage examples.

Method 2: Clone the Component Library Repo

For bulk component access, clone the component library repository and copy the components you need into your project.

---

Component Naming Convention

All components in the library are prefixed with O (for "OS" - Order Stack):

Component	File Name	Description
OInput	OInput.vue	Text input field
OButton	OButton.vue	Button component
OCheckbox	OCheckbox.vue	Checkbox input
ODropdown	ODropdown.vue	Dropdown select
OToast	OToast.vue	Toast notifications
OModal	OModal.vue	Modal dialogs
OTable	OTable.vue	Data table

Why the "O" Prefix?

The prefix helps distinguish library components from your custom components and avoids naming conflicts with HTML elements or other libraries.

---

Using Components

Basic Usage

Import components from @/components/sharedComponents/ and use them in your templates. Each component's documentation page includes detailed usage examples, API reference for props, events, and slots.

---

Customizing Components

Modifying Component Styles

First Priority: Modify the Component Itself

When you need to customize a component's appearance or behavior, always modify the component file directly first:

1. Open the component file in src/components/sharedComponents/
2. Edit the <style> section to match your project's design patterns
3. Update colors, spacing, typography, and other design tokens
4. Replace hardcoded values with your project's SCSS variables
5. Adjust styles to align with your project's design system

This approach ensures consistency across your project and makes the component truly yours.

Overriding Styles in Parent Components

If you need to override component styles from a parent component (without modifying the component itself), use one of these methods:

Option 1: Using :deep() Selector

Use the :deep() selector in a scoped style block to target child component styles:

<style lang="scss" scoped>
:deep(.o-button) {
  background-color: $your-primary-color;
  border-radius: 8px;
}
</style>

Option 2: Style Tag Without Scoped

Use a non-scoped style tag to override component styles:

<style lang="scss">
.o-button {
  background-color: $your-primary-color;
  border-radius: 8px;
}
</style>

Style Override Priority

• First: Modify the component itself (recommended for project-wide consistency)
• Second: Use :deep() or non-scoped styles in parent components (for specific use cases)

Extending Components

Create wrapper components to add functionality or customize behavior while keeping the original component intact.

Example: Creating a Custom Button Wrapper

<!-- src/components/MyButton.vue -->
<script setup>
import OButton from "@/components/sharedComponents/OButton.vue";

const props = defineProps({
  // Add custom props
  analytics: String,
});

const emit = defineEmits(["click"]);

const handleClick = (event) => {
  // Add custom logic (e.g., analytics tracking)
  if (props.analytics) {
    console.log("Button clicked:", props.analytics);
  }
  emit("click", event);
};
</script>

<template>
  <OButton v-bind="$attrs" @click="handleClick">
    <slot />
  </OButton>
</template>

Now you can use MyButton with additional functionality while keeping the original OButton component unchanged.

---

Theming

Setting Up Themes

Theme variables are managed in src/assets/scss/dynamicVariables.css using CSS custom properties (CSS variables).

Light Theme (Default)

Light theme variables are defined in the :root selector:

:root {
  --unbounded-font: "Unbounded", sans-serif;
  --primary-color: #000000;
  --color-white: #ffffff;
  --color-black: #000000;
  --border-white: #ffff;
  --border-black: #000;
  --background-white: #fff;
  --background-black: #000;
}

Dark Theme

Dark theme variables are defined in the .dark class. Override the variables you need for dark mode:

.dark {
  --primary-color: #ffffff;
  --color-white: #000000;
  --color-black: #ffffff;
  /* Override variables for dark theme */
}

Design System Reference

Before adding any color variables, refer to the design system documentation linked in the dynamicVariables.css file comments.

Theme Switching

Theme switching is implemented by toggling the .dark class on the document element:

// Toggle dark theme
document.documentElement.classList.toggle("dark");

// Or set explicitly
document.documentElement.classList.add("dark"); // Enable dark theme
document.documentElement.classList.remove("dark"); // Enable light theme

When the .dark class is present on the document element, all CSS variables defined in .dark will override the :root variables, effectively switching the theme.

Using Theme Variables in Components

Reference these CSS variables in your component styles:

.my-component {
  background-color: var(--background-white);
  color: var(--color-black);
  border: 1px solid var(--border-black);
}

---

Best Practices

Organize Components by Type

Keep library components in sharedComponents/ folder, your common components in a separate folder, and feature-specific components organized by feature.