@blockbite/docs 0.1.1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@blockbite/docs",
+  "version": "0.1.1",
+  "description": "Blockbite public documentation content in MDX format",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "public"
+  ],
+  "exports": {
+    "./src/*": "./src/*",
+    "./public/*": "./public/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@mdx-js/rollup": "^3.1.1",
+    "@vitejs/plugin-react": "^4.4.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "vite": "^6.3.4"
+  }
+}

package/src/01-introduction/01-installation.mdx

@@ -0,0 +1,57 @@
+---
+title: "Installation"
+description: "How to install the Blockbite WordPress plugin."
+tags: ["wordpress", "installation", "plugin"]
+---
+
+# Installation
+
+Follow these steps to install the Blockbite plugin on your WordPress site.
+
+<Stepper>
+<StepperItem title="Download the Plugin">
+  Download the latest version of the plugin from the official GitHub repository.
+
+1.  Go to the [Blockbite Releases Page](https://github.com/block-bite/blockbite/releases).
+2.  Find the latest release.
+3.  Under the "Assets" section, download the `blockbite.zip` file.
+
+{" "}
+
+<Alert>
+  <AlertCircleIcon />
+  <AlertTitle>Can't find the file?</AlertTitle>
+  <AlertDescription>
+    Make sure you download the `blockbite.zip` file and not the source code.
+  </AlertDescription>
+</Alert>
+
+</StepperItem>
+<StepperItem title="Upload to WordPress">
+  Add the plugin to your WordPress site.
+
+1.  Log in to your WordPress admin dashboard.
+2.  In the left-hand menu, navigate to **Plugins > Add New**.
+3.  At the top of the page, click the **Upload Plugin** button.
+4.  Click **Choose File** and select the `blockbite.zip` file you downloaded earlier.
+5.  Click **Install Now**.
+
+</StepperItem>
+<StepperItem title="Activate the Plugin">
+  Once the plugin is installed, let's activate it.
+
+1.  After the installation is complete, you should see a success message.
+2.  Click the **Activate Plugin** button.
+
+{" "}
+
+<Alert>
+  <CheckCircle2Icon />
+  <AlertTitle>Installation Complete!</AlertTitle>
+  <AlertDescription>
+    Congratulations! Blockbite is now installed and activated on your site.
+  </AlertDescription>
+</Alert>
+
+</StepperItem>
+</Stepper>

package/src/01-introduction/02-getting-started.mdx

@@ -0,0 +1,45 @@
+---
+title: "Getting Started"
+description: "Learn the basics of using the Blockbite plugin in the WordPress editor."
+tags: ["wordpress", "getting started", "basics"]
+---
+
+# Getting Started
+
+Welcome to Blockbite! This guide will help you get started with using the plugin to unlock advanced design capabilities within the WordPress block editor.
+
+## Open Blockbite Settings
+
+Before editing blocks, open the plugin settings page in wp-admin so you can confirm your project connection and defaults. In WordPress admin, go to the left menu and click `Blockbite`.
+
+![Blockbite settings page (Projects tab)](/docs/screenshots/settings/projects.png#w=960&h=600)
+
+If the Blockbite options are collapsed in the editor sidebar, expand them first so the control groups are visible.
+
+![Toggle Blockbite options in sidebar](/docs/screenshots/sidebar/toggle-blockbite-options.png)
+
+## Start editing in the visual editor
+
+After confirming settings, go to the block editor and start styling blocks with Blockbite.
+
+1. Select a block in the WordPress editor (for example Paragraph, Heading, or Image).
+2. Open the right sidebar (`Ctrl + Shift + ,` on Windows or `⌘ + Shift + ,` on Mac).
+3. Expand the **Blockbite** panel and start adjusting controls.
+
+## User roles tab
+
+Use this tab to restrict who can access the Blockbite editor in wp-admin. This is useful when you want only trusted roles to change block structures and styling rules.
+
+![User roles settings tab](/docs/screenshots/settings/user-roles.png#w=960&h=600)
+
+- `Restrict Blockbite Editor to Admins only`: Limits editor access to administrators only. Non-admin roles (for example Editors) will not be able to use Blockbite when enabled.
+
+## Explore Further
+
+This section serves as your starting point. To learn more about specific features and advanced usage, check out the following guides:
+
+- [Design Panel Basics](/docs/core-concepts/design-panel-basics)
+- [Code Editor & Live Preview](/docs/core-concepts/code-editor-livepreview)
+- [Dynamic Templates](/docs/core-concepts/dynamic-templates)
+- [Design Framework Introduction](/docs/design-framework/introduction)
+- [Platform Sync](/docs/advanced-guides/platform-sync)

package/src/01-introduction/03-contributing.mdx

@@ -0,0 +1,9 @@
+---
+title: "Contributing"
+description: "A description for Contributing."
+tags: []
+---
+
+# Contributing
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.

package/src/01-introduction/04-quick-learn.mdx

@@ -0,0 +1,37 @@
+---
+title: "Quick Learn"
+description: "Fast path to learn the Blockbite editor workflow."
+tags: ["quick learn", "basics"]
+---
+
+# Quick Learn
+
+This is the shortest path to become productive with Blockbite. Follow these steps in order and you will cover settings, visual editing, responsive controls, and token basics quickly.
+
+## 1. Open settings and connect
+
+Go to `Blockbite` in wp-admin and confirm your project settings are configured.
+
+## 2. Open the visual editor
+
+Select a block, open the right sidebar, and expand **Blockbite**.
+
+## 3. Navigate style categories fast
+
+Use the 9 tiles in the start state to jump directly to a style category.
+
+## 4. Apply responsive styles
+
+Use responsive targeting (for example `Mobile & Tablet Only`) to scope styles without changing your current viewport context.
+
+## 5. Add Tailwind classes quickly
+
+Add space-delimited Tailwind classes, press Enter, then use copy/paste actions to transfer classes between selected blocks.
+
+## Next docs
+
+- [Getting Started](/docs/introduction/getting-started)
+- [Tailwind & Visual Editor](/docs/core-concepts/tailwind-css)
+- [Design Tokens](/docs/design-framework/design-tokens)
+- [Platform Sync](/docs/advanced-guides/platform-sync)
+- [CLI Commands](/docs/cli/command-reference)

package/src/02-core-concepts/01-introduction.mdx

@@ -0,0 +1,17 @@
+---
+title: "Introduction"
+description: "Core ideas behind Blockbite's visual-to-code workflow."
+tags: ["core", "basics"]
+---
+
+# Introduction
+
+Core Concepts are the foundation of how Blockbite works.
+
+Blockbite is built around a simple loop:
+
+1. Design visually in the panel.
+2. Refine details in code when needed.
+3. Reuse logic with templates and dynamic data.
+
+If you are new to the platform, read this section in order before moving to Design Framework or AI Studio.

package/src/02-core-concepts/02-tailwind-css.mdx

@@ -0,0 +1,51 @@
+---
+title: "Tailwind & Visual Editor"
+description: "How Tailwind is used inside Blockbite projects."
+tags: ["tailwind", "styling"]
+---
+
+# Tailwind & Visual Editor
+
+Blockbite uses utility-first styling patterns compatible with Tailwind CSS.
+
+The visual editor is where you apply Tailwind-driven styling directly to selected blocks. Open any block, expand the Blockbite panel in the right sidebar, and use the control groups to adjust layout, dimensions, and visual styles.
+
+## Finding the Blockbite controls
+
+Once you've installed and activated the plugin, the controls are available in the block settings sidebar.
+
+1. Select any block in the WordPress editor (for example Paragraph, Heading, or Image).
+2. Open the block settings sidebar on the right (`Ctrl + Shift + ,` on Windows or `⌘ + Shift + ,` on Mac).
+3. Expand the **Blockbite** panel to access the visual editor controls.
+
+## UI editor start state and fast navigation
+
+When you open the visual editor, the default state shows 9 category tiles. These tiles are designed as a fast navigation layer to jump directly into a style category.
+
+![UI editor start state with 9 category tiles](/docs/screenshots/tailwind/ui-editor/start.png)
+
+You can also open the category dropdown and search style groups directly.
+
+![Category search and autocomplete](/docs/screenshots/tailwind/ui-editor/search-autocomplete.png)
+
+## Responsive control behavior
+
+The responsive selector lets you choose where a style applies (for example `Mobile & Tablet Only`). We do not auto-switch the editor viewport when you change this, so you can continue styling rapidly without context jumps.
+
+When your editor is already in a mobile viewport, the responsive control automatically targets mobile.
+
+![Responsive control (Mobile & Tablet Only)](/docs/screenshots/tailwind/ui-editor/responsive-classes.png)
+
+## Tailwind class input, copy, and paste
+
+The Tailwind input accepts classes one after another as space-delimited tokens. Press Enter and the classes are applied immediately to the selected block.
+
+You can use the small buttons under the input to copy or paste class strings between blocks.
+
+Example copied class string:
+
+`flex justify-start items-stretch relative w-full flex-row max-lg:flex-col`
+
+Select another block and paste to apply the same class setup quickly.
+
+![Tailwind class input with copy/paste actions](/docs/screenshots/tailwind/ui-editor/tailwind-class-input.png)

package/src/02-core-concepts/03-design-panel-basics.mdx

@@ -0,0 +1,22 @@
+---
+title: "Design Panel Basics"
+description: "Understand the main controls in the Blockbite design panel."
+tags: ["design panel", "ui"]
+---
+
+# Design Panel Basics
+
+The Design Panel is where you configure structure, style, and behavior for a block.
+
+## Key areas
+
+- Layout: size, spacing, position, alignment.
+- Visual: color, border, radius, effects.
+- Content: text, rich content, dynamic bindings.
+- Advanced: class hooks, custom attributes, and metadata.
+
+## Best practices
+
+- Apply changes in small increments and preview often.
+- Keep naming consistent for reusable blocks.
+- Prefer shared tokens over hard-coded values.

package/src/02-core-concepts/04-code-editor-livepreview.mdx

@@ -0,0 +1,22 @@
+---
+title: "Code Editor & Live Preview"
+description: "Edit generated code and validate changes instantly."
+tags: ["editor", "preview"]
+---
+
+# Code Editor & Live Preview
+
+Use the code editor when visual controls are not enough.
+
+## How it works
+
+- The editor updates source output directly.
+- Live Preview renders your changes in real time.
+- Validation errors are surfaced immediately so you can fix quickly.
+
+## Practical flow
+
+1. Start in the Design Panel.
+2. Open Code Editor for precise adjustments.
+3. Confirm behavior in Live Preview.
+4. Save as a reusable template if the pattern repeats.

package/src/02-core-concepts/05-deprecating-presets.mdx

@@ -0,0 +1,22 @@
+---
+title: "Deprecating Presets"
+description: "Preset support is removed. Migration is required."
+tags: ["deprecation", "migration"]
+---
+
+# Deprecating Presets
+
+Presets are deprecated and no backward compatibility is provided.
+
+## Policy
+
+- Legacy preset behavior is not maintained.
+- Existing preset-based setups must be migrated.
+- New work should use Dynamic Templates and token-driven configuration.
+
+## Migration path
+
+1. Identify blocks relying on presets.
+2. Rebuild those patterns as Dynamic Templates.
+3. Move style values to tokens.
+4. Validate output in Live Preview before release.

package/src/02-core-concepts/06-dynamic-templates.mdx

@@ -0,0 +1,21 @@
+---
+title: "Dynamic Templates"
+description: "Build reusable templates powered by variables and bindings."
+tags: ["templates", "dynamic"]
+---
+
+# Dynamic Templates
+
+Dynamic Templates allow one block definition to power many outputs.
+
+## Core idea
+
+A template defines structure once and reads data from fields at runtime.
+
+## When to use
+
+- Repeated UI patterns with changing content.
+- Multi-tenant or multi-brand outputs.
+- Any block you expect to maintain long term.
+
+See also: [Dynamic Templates in Dynamic Content](/docs/dynamic-content/dynamic-templates)

package/src/02-core-concepts/07-fills.mdx

@@ -0,0 +1,21 @@
+---
+title: "Fills"
+description: "Use fills to inject contextual content into shared structures."
+tags: ["fills", "content"]
+---
+
+# Fills
+
+Fills are insertion points for dynamic or contextual content.
+
+## Typical use cases
+
+- Slotting CTA content into a shared card pattern.
+- Replacing media/text regions across variants.
+- Supplying channel-specific content without duplicating layout.
+
+## Guidelines
+
+- Keep fill contracts explicit (required vs optional).
+- Document expected shape for each fill.
+- Validate fallback behavior when a fill is missing.

package/src/02-core-concepts/08-cdn-libraries.mdx

@@ -0,0 +1,36 @@
+---
+title: "CDN Libraries"
+description: "Load approved third-party libraries through CDN integration."
+tags: ["cdn", "libraries"]
+---
+
+# CDN Libraries
+
+Blockbite supports external libraries via CDN for controlled extensions.
+
+Use the CDN Libraries settings tab to register handles and map each handle to a concrete URL. This lets you keep library loading explicit and version-pinned.
+
+![CDN libraries picker open](/docs/screenshots/settings/cdn-libraries-picker-open.png#w=960&h=600)
+
+- `CDN HANDLES`: Multi-select input for library handles.
+- Dropdown results (for example `gsap_core`, `gsap_scrolltrigger`): Predefined handle suggestions.
+- Custom handle input: You can type your own handle and confirm with Enter.
+
+![CDN libraries selected handles](/docs/screenshots/settings/cdn-libraries-picker.png#w=960&h=600)
+
+- Selected handle chips: Active libraries that will get URL fields below.
+- Per-handle URL field: Configure provider, version, or exact path.
+- Drag handle icon: Reorder loaded libraries.
+- Delete icon: Remove a handle and its URL mapping.
+
+## Recommendations
+
+- Only use trusted, version-pinned CDN URLs.
+- Minimize runtime dependencies.
+- Verify license and production impact before enabling.
+
+## Operational checks
+
+1. Pin a fixed version.
+2. Test in preview and production build.
+3. Track loaded libraries in project documentation.

package/src/03-design-framework/01-introduction.mdx

@@ -0,0 +1,17 @@
+---
+title: "Introduction"
+description: "Overview of the Blockbite design framework layer."
+tags: ["framework", "design"]
+---
+
+# Introduction
+
+The Design Framework defines how style decisions stay consistent across blocks.
+
+It combines tokens, schema, components, and patterns into one predictable system.
+
+We created a simplified schema `v1` that keeps bites stable by always including tokens in the structure. This lets you reuse blocks and change colors/themes without breaking the design system.
+
+Our approach is semantic design tokens (for example intent-based names instead of raw color values), and we would love feedback from teams using this in production.
+
+- Token implementation reference: [designtokens.ts](https://github.com/block-bite/blockbite/blob/main/packages/shared-utils/src/designtokens.ts)

package/src/03-design-framework/02-design-tokens.mdx

@@ -0,0 +1,35 @@
+---
+title: "Design Tokens"
+description: "Set up reusable semantic values for spacing, color, type, and more."
+tags: ["tokens", "design system"]
+---
+
+# Design Tokens
+
+Design tokens are the single source of truth for reusable values.
+
+Blockbite uses a semantic token model so style decisions stay portable across bites and themes. Tokens are managed in a dedicated modal with category tabs for sizing, colors, families, headings, and sync.
+
+![Design tokens modal](/docs/screenshots/design-framework/design-tokens.png)
+
+## Token categories in the editor
+
+The token modal is split into categories so each token type can be managed independently without mixing concerns.
+
+![Font sizes tokens](/docs/screenshots/design-framework/design-tokens/fonts-sizes.png)
+![Color tokens](/docs/screenshots/design-framework/design-tokens/colors.png)
+![Heading tokens](/docs/screenshots/design-framework/design-tokens/headings.png)
+
+## Token categories
+
+- Color
+- Spacing
+- Typography
+- Radius
+- Shadow
+
+Use semantic naming (`surface-primary`, `text-muted`) over raw naming (`blue-500`).
+
+## Sync tab (Figma)
+
+You can use the `Sync` tab to synchronize design tokens from your connected Figma project into Blockbite. This keeps the token source aligned between design and implementation.

package/src/03-design-framework/03-schema-v1.mdx

@@ -0,0 +1,18 @@
+---
+title: "Schema (v1)"
+description: "Structure and constraints for framework configuration in v1."
+tags: ["schema", "v1"]
+---
+
+# Schema (v1)
+
+Schema v1 defines the contract between design data and rendered output.
+
+## Scope
+
+- Token definitions
+- Component mappings
+- Namespace boundaries
+- Validation constraints
+
+Keep schema files versioned and reviewed like code.

package/src/03-design-framework/04-svgs.mdx

@@ -0,0 +1,16 @@
+---
+title: "Svgs"
+description: "Guidelines for inline and referenced SVG usage in Blockbite."
+tags: ["svg", "assets"]
+---
+
+# Svgs
+
+Use SVGs for scalable, theme-friendly graphics.
+
+## Rules
+
+- Prefer optimized SVGs.
+- Remove unnecessary metadata before import.
+- Use token-aware fill/stroke when possible.
+- Keep icon viewboxes consistent.

package/src/03-design-framework/05-bite-components.mdx

@@ -0,0 +1,18 @@
+---
+title: "Bite Components"
+description: "Composable component units used throughout the design framework."
+tags: ["components", "bite"]
+---
+
+# Bite Components
+
+Bite Components are reusable primitives and composites that align with your schema.
+
+## Expectations
+
+- Typed inputs
+- Predictable variants
+- Clear content slots
+- Token-driven styling
+
+Avoid embedding one-off business rules inside component definitions.

package/src/03-design-framework/06-block-patterns.mdx

@@ -0,0 +1,16 @@
+---
+title: "Block Patterns"
+description: "Pattern-driven block composition for repeatable layouts."
+tags: ["patterns", "layout"]
+---
+
+# Block Patterns
+
+Block Patterns package common layouts into reusable templates.
+
+## Pattern quality checklist
+
+- Solves a repeated use case.
+- Has clear defaults.
+- Supports dynamic fields.
+- Keeps overrides minimal and safe.

package/src/03-design-framework/07-namespaces.mdx

@@ -0,0 +1,17 @@
+---
+title: "Namespaces"
+description: "Use namespaces to isolate tokens, components, and patterns."
+tags: ["namespaces", "organization"]
+---
+
+# Namespaces
+
+Namespaces prevent collisions and keep large projects maintainable.
+
+## Suggested model
+
+- `core/*` for shared platform assets
+- `brand/*` for tenant-specific overrides
+- `feature/*` for domain-scoped implementations
+
+Document ownership per namespace.

package/src/04-ai-studio/01-introduction.mdx

@@ -0,0 +1,33 @@
+---
+title: "Introduction"
+description: "AI Studio overview and model-provider workflow."
+tags: ["ai", "studio"]
+---
+
+# Introduction
+
+AI Studio helps generate and refine Blockbite structures faster.
+
+Use it for scaffolding, transformation, and assisted prompt iteration.
+
+## Add API key
+
+Connect your provider key in the AI tab before using model-backed integrations. Once connected, Blockbite can fetch models and run your selected AI flows.
+
+![Add API key in AI settings](/docs/screenshots/settings/ai/add-api-key.png#w=960&h=612)
+
+- `API Keys` tab: Lists provider key forms.
+- `MISTRAL API KEY`: Input for your Mistral secret key.
+- Visibility icon: Toggle key visibility while editing.
+- `Connect`: Validates and stores the API key.
+- `+ Add Provider`: Adds another AI provider connection.
+
+## Load default templates
+
+Use this area to bootstrap model-specific defaults before writing custom prompts. It gives you a fast baseline that you can then tune per project.
+
+![Load defaults control](/docs/screenshots/settings/ai/load-defaults-button.png#w=960&h=600)
+
+- `Platform selector` (for example `Mistral`): Chooses the provider profile.
+- `Load defaults`: Inserts the default integration templates for the selected platform.
+- `Model`: Picks the concrete model variant for generation.