Core Concepts

Welcome to the engine room. While the Packages Overview covers what each package does, this section explains the design philosophies and technical patterns that unite the entire ArtisanPack UI ecosystem.

These guides cover the "how-to" for cross-cutting concerns that apply to multiple packages, helping you build a consistent, modern, and accessible application.

Styling & Theming

ArtisanPack UI is built with a distinct, modern, and clean aesthetic in mind. Our components are designed to be beautiful out-of-the-box while giving you the flexibility to customize them.

This guide covers the core visual principles of the ArtisanPack UI design system.

Font: Poppins

We use the Poppins font family for all text. It's a versatile and clean sans-serif font that works beautifully for UI elements, headings, and body copy.

We recommend importing it from Google Fonts in your main layout file:

Color Palette

Our color system is built for a striking light and dark mode.

Dark Mode: Utilizes bright, neon-style accent colors for a modern, tech-focused feel.
Light Mode: Uses slightly darker, more saturated versions of the same accent colors to ensure they pass WCAG contrast ratios against a light background.

You will find these colors pre-configured in packages like Livewire UI Components and the CMS Framework.

Light & Dark Mode

All UI components are built to be fully compatible with Tailwind CSS's dark: variant. We recommend using the window.matchMedia strategy or a simple Alpine.js component to toggle a .dark class on the <html> element.

// Example Alpine.js-based theme switcher
<div x-data="{
theme: localStorage.getItem('theme') || 'system',
init() {
this.updateTheme(this.theme);
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', e => {
if (this.theme === 'system') {
this.updateTheme('system');
}
});
},
updateTheme(theme) {
this.theme = theme;
localStorage.setItem('theme', theme);
if (theme === 'system') {
document.documentElement.classList.toggle('dark', window.matchMedia('(prefers-color-scheme: dark)').matches);
} else {
document.documentElement.classList.toggle('dark', theme === 'dark');
}
}
}">
<button @click="updateTheme('light')">Light</button>
<button @click="updateTheme('dark')">Dark</button>
<button @click="updateTheme('system')">System</button>
</div>

Core UI Patterns

You'll see a few consistent styling patterns across our components that define our look.

Rounded Borders

We default to soft, rounded corners for most elements like buttons, cards, and inputs.

Classes: rounded-lg or rounded-xl

"Glass" Backgrounds

For elements like sidebars, headers, and modal backgrounds, we often use a semi-transparent "glass" effect that blurs the content behind it.

Classes: bg-white/50 dark:bg-gray-900/50 backdrop-blur-lg

Gradient Borders

A signature element in our design (often used on footers or cards) is a subtle gradient border. This is typically achieved by wrapping an element in a container with a gradient background and inner padding.

Example HTML:
<div class="p-[2px] rounded-lg bg-gradient-to-r from-cyan-500 to-blue-500">
<div class="bg-white dark:bg-gray-900 rounded-[6px] p-4">

</div>
</div>

Accessibility First

In the ArtisanPack UI ecosystem, accessibility is not an "add-on" or an afterthought—it is a core design requirement. We believe that empowering developers also means empowering them to build applications that are usable by everyone.

Our Guiding Principles

Our approach to accessibility is guided by the Web Content Accessibility Guidelines (WCAG), with a focus on practical, developer-friendly implementation.

Keyboard Navigation: All interactive components, from dropdowns to drag-and-drop interfaces, are designed to be fully operable with a keyboard.
Screen Reader Support: We use semantic HTML and ARIA attributes (when necessary) to ensure our components provide clear, useful context to screen reader users.
Contrast & Readability: Our default color palettes are designed to meet WCAG contrast ratios. We also use a clear, readable font (Poppins) to enhance legibility.

Philosophy in Practice

You can see this philosophy in action in our packages:

Livewire Drag and Drop: This package was built from the ground up to be "accessibility-first," featuring full keyboard navigation and screen reader support, something notoriously difficult to implement correctly.
Accessibility Package: This utility package provides tools and helpers to make implementing accessibility features in your own custom code simpler.
Livewire UI Components: Our components are built with accessibility in mind, handling details like aria-expanded attributes, focus management, and proper role assignments.

We handle the complex parts of accessibility so you can focus on building your application, confident that the foundation is solid.

Frontend Philosophy (TALL Stack)

ArtisanPack UI is built to thrive on the modern TALL stack. This choice is deliberate, as it aligns perfectly with our goal of empowering Laravel developers to build powerful, dynamic applications with maximum efficiency.

The TALL Stack is: Tailwind CSS, Alpine.js, Livewire, and Laravel.

Why the TALL Stack?

Productivity: It allows you to build complex, reactive user interfaces without ever leaving the comfort of PHP and Blade. This context-switching reduction is a massive productivity boost.
Full-Stack Power: Livewire provides a seamless bridge between your Laravel backend and your frontend UI. You write PHP methods, and Livewire handles the JavaScript reactivity automatically.
Utility-First Styling: Tailwind CSS gives you complete control over your design system without writing custom CSS. It's the perfect companion for building reusable, consistent Blade components.
Lightweight Interactivity: Alpine.js provides the "sprinkle" of client-side JavaScript for handling small interactions like toggling modals or dropdowns, all within your HTML.

Our Recommended Stack: TALL

While many of our packages (like Security, Code Style, or Icons) are frontend-agnostic and can be used in any Laravel project, you will get the absolute most value from ArtisanPack UI by adopting the TALL stack.