Core Principles

Every decision, from a line of code to a marketing headline, is guided by these four principles.

1. Privacy First, Always

Our foundational promise. All tools must function entirely on the client-side. No user data, files, or inputs are ever sent to a server. This is non-negotiable. We build trust by eliminating the need for it.

2. Performance by Default

Our tools must be instant. We achieve this through client-side processing, minimal dependencies, and optimized code. Users should feel the speed. Once a tool is loaded, it should be available offline.

3. Aesthetic Minimalism

Our design is clean, modern, and focused. We use a dark, professional theme with clear visual hierarchy. Every element must serve a purpose. We avoid clutter to keep the user focused on their task.

4. Zero Friction

No sign-ups, no pop-ups, no cookie banners, no nonsense. The path from arriving on the site to using a tool should be as short as possible. Value is delivered instantly.

Foundations

Colors

Our palette is built on a dark foundation with functional, accessible accent colors. It is optimized for clarity, focus, and a professional aesthetic.

Primary & Neutrals

Functional Colors

Typography

We use the Inter font family for its clarity and modern feel. Roboto Mono is used for code and technical displays.

Iconography

Icons should be clean, minimalist line icons. The preferred style is stroke-width 1.5 for a balanced, modern look. Icons should be sourced from a consistent library (like Heroicons or a custom set) to maintain visual harmony.

Spacing

We use a consistent 4px-based spacing scale for padding, margins, and gaps to ensure visual harmony.

Borders & Shadows

Borders are subtle, used to define containers. Shadows are minimal, used to imply elevation on hover.

Language & Tone

Our voice is confident, clear, and empowering. We speak directly to creators and developers.

• Clarity over cleverness: Be direct. "Free, Private, Browser-Based Apps" is better than "Unleash Your Digital Potential."
• Use active voice: "Create animated GIFs" instead of "Animated GIFs can be created."
• Focus on benefits: Explain *why* a feature matters (e.g., "client-side for complete privacy").
• Keywords: Use terms our audience searches for: "generator," "converter," "editor," "maker," "privacy-first."

Animation & Motion

Motion should be purposeful, providing feedback without being distracting. We use simple, fast transitions.

• Standard Transition: transition-colors duration-200 ease-in-out is the default for interactive elements like buttons and links.
• Transformations: Use subtle transforms like hover:translate-y-[-2px] or group-hover:translate-x-1 for micro-interactions.
• Modal/Toast Animations: Modals and toasts use transform and opacity transitions for smooth appearance and disappearance (e.g., transform .3s ease-in-out).

Components

Reusable components are the building blocks of Solite. They must be consistent in style and behavior to create a predictable and intuitive user experience.

Buttons

Buttons are styled based on their importance and function.

Links

Links are styled to be easily identifiable and accessible. They have a distinct color and a clear hover state.

Headers

Main Site Header

The primary header for the homepage and blog index. Clean, simple, with a primary CTA.

Tool Page Header

Used on individual tool pages. Includes the app name for context. Adapts to a stacked layout on mobile for better readability.

Cards

The standard card component for displaying tools. It features a subtle background, border, and a lift-on-hover effect.

Tool Card (Alternative)

A more compact card for dense lists of tools or resources.

Blog Post Card (Compact)

A more compact card for featuring articles in a grid. The icon and text are side-by-side on larger screens.

Blog Post Card

Used on the blog index to feature articles. Includes a large icon area and clear typography.

Headings

Consistent heading styles create a clear visual hierarchy and improve readability. This applies to both app pages and blog content.

Dividers

Dividers are used to separate content visually. They should be subtle.

Dropdowns

Dropdowns are used to reveal a list of actions or links.

Data Display

Badges

Badges are used to highlight status, counts, or short labels. They should be small and unobtrusive.

Form Elements

Form elements are designed for clarity, accessibility, and ease of use. They feature clear labels, consistent focus states, and a dark, modern aesthetic.

Description List

Description lists are perfect for displaying key-value pairs of data, such as user profile information or item specifications.

Avatars

Avatars are used to represent users or entities. They can be images or placeholders.

TW

+3

Modals / Dialogs

Modals are used to display critical information or require user input for a specific task. They appear on top of the main content.

Feedback & Alerts

Alerts provide contextual feedback messages for user actions. Use them to notify users of success, errors, or important information.

Component States

Clearly communicating the state of the application is crucial for a good user experience. This includes loading, empty, and error states.

Empty State

When a component has no data to display, it should guide the user on what to do next. This is often seen in the initial view of a tool.

Loading State

For actions that take a moment (e.g., client-side processing of a large file), provide visual feedback. A simple pulsing animation or a spinner is effective.

Buttons should use the disabled attribute and a visual cue (e.g., disabled:opacity-50) during processing.

Navigation & Interaction

Tabs

Tabs are used to organize and allow navigation between groups of content that are related and at the same level of hierarchy.

Pagination

Pagination is used for splitting up content into several pages, and enables users to navigate between these pages.

Listbox / Dropdown Select

Listboxes are a more robust and styleable alternative to the native <select> element. They are used to select a value from a list of options and are fully accessible, following WAI-ARIA patterns.

SEO & AI Authority Block

This is a unique and mandatory feature on every tool page. At the bottom of the page, before the footer, a <details> block contains a comprehensive, human-readable, and AI-crawlable summary of the tool.

Purpose: This block acts as a rich content snippet that boosts SEO authority and provides structured data for AI models and search engines, explaining the tool's value proposition clearly.

Core Patterns & Practices

App Layouts

Most tools use a multi-pane layout (2 or 3 columns) on desktop, which collapses into a single view on mobile. The main content area typically occupies 80% of the width on large screens, with a 20% ad sidebar. The main content area itself is a flex or grid container for the panes.

Accessibility (a11y)

Building for everyone is a core requirement. All tools must be accessible.

• Keyboard Navigation: All interactive elements (buttons, links, inputs) must be focusable and operable via the keyboard. Use logical focus order.
• Semantic HTML: Use HTML tags for their correct purpose (<nav>, <main>, <button>, etc.). This is the foundation of accessibility.
• ARIA Roles: Use ARIA (Accessible Rich Internet Applications) roles where necessary, especially for complex components like modals (role="dialog", aria-modal="true") and listboxes.
• Labels: All form inputs must have an associated <label>. Icons used as buttons must have an aria-label.
• Color Contrast: Text must have sufficient contrast against its background. Our color palette is designed with this in mind, but always verify.

Interaction

Drag-and-drop zones should clearly indicate their active state. A dashed border should turn solid blue (border-blue-500) on drag-over to provide clear visual feedback.

Mobile Navigation

On mobile screens (<1024px), complex layouts should collapse into a tabbed view controlled by a bottom navigation bar. This bar provides quick access to the "Preview" and "Controls" panes, ensuring a consistent and usable experience on smaller devices.

JavaScript & App Logic

Application logic is built with pure, modern vanilla JavaScript to ensure maximum performance and zero dependencies.

• Technology: No frameworks like React or Vue. All logic is self-contained.
• Structure: Logic is typically placed in a single <script> tag at the end of the <body>. For more complex apps, it can be organized into a class.
• DOM Management: A DOMContentLoaded listener is the entry point. An object (often named el) should be used to cache all necessary DOM elements on load for performance.
• State Management: App state is managed with simple variables. For persistence across sessions, localStorage is used to save user input or settings (e.g., localStorage.setItem('solite-tool-content', content)).
• Event Handling: Event listeners are attached directly to elements. A debounce utility function is commonly used to prevent expensive operations (like re-rendering a preview on an input event) from firing too frequently.
• File Handling: All file operations must be client-side. Use browser APIs like FileReader for uploads and Blob/URL.createObjectURL for generating downloads.

SEO & Metadata

Every tool page is a landing page. It must be optimized to be found.

1. Title Tag: Lead with the primary keyword. Format: [Tool Name] | [Benefit/Feature] | Solite. Example: Free Image Compressor | Compress JPG, PNG, WebP | Solite.
2. Meta Description: Write a compelling summary (under 160 characters). Include primary keywords and the core value props (free, private, online, no sign-up).
3. Meta Keywords: Include a comprehensive list of relevant search terms.
4. Canonical URL: Always specify the canonical URL to prevent duplicate content issues.
5. Schema.org Markup: Use a detailed application/ld+json script to define the WebApplication, Organization, and FAQPage schemas. This is critical for search engine understanding.
6. Open Graph & Twitter Cards: Ensure og:title, og:description, and og:image are set for optimal social sharing. Use a service like microlink.io for dynamic screenshots if a static image is not available.
7. Semantic HTML & Authority Block: Use h1, h2, h3 hierarchically. Every tool page must include the "SEO & AI Authority Block" at the bottom, structured with a <details> tag, containing a rich, keyword-dense explanation of the tool's purpose, features, and benefits.