docs: restructure docs IA and landing pages

apps/backgrounds/package.json

@@ -16,7 +16,7 @@
     "@react-three/fiber": "9.1.2",
     "clsx": "^2.1.1",
     "motion": "^12.11.0",
-    "next": "16.1.6",
+    "next": "16.2.4",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "shadergradient": "^1.2.14",

apps/blog/docusaurus.config.ts

@@ -13,10 +13,12 @@ const config: Config = {
   organizationName: "gridaco",
   projectName: "grida",
   onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "warn",
 
   markdown: {
     mermaid: true,
+    hooks: {
+      onBrokenMarkdownLinks: "warn",
+    },
   },
 
   themes: ["@docusaurus/theme-mermaid"],

apps/blog/package.json

@@ -16,20 +16,20 @@
     "write-translations": "docusaurus write-translations"
   },
   "dependencies": {
-    "@docusaurus/core": "3.9.2",
-    "@docusaurus/plugin-sitemap": "3.9.2",
-    "@docusaurus/preset-classic": "3.9.2",
-    "@docusaurus/theme-mermaid": "3.9.2",
+    "@docusaurus/core": "3.10.0",
+    "@docusaurus/plugin-sitemap": "3.10.0",
+    "@docusaurus/preset-classic": "3.10.0",
+    "@docusaurus/theme-mermaid": "3.10.0",
     "@mdx-js/react": "^3.1.0",
     "clsx": "^2.1.1",
     "prism-react-renderer": "^2.4.1",
     "react": "19.2.1",
     "react-dom": "19.2.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.9.2",
-    "@docusaurus/tsconfig": "3.9.2",
-    "@docusaurus/types": "3.9.2",
+    "@docusaurus/module-type-aliases": "3.10.0",
+    "@docusaurus/tsconfig": "3.10.0",
+    "@docusaurus/types": "3.10.0",
     "typescript": "^5"
   },
   "browserslist": {

apps/docs/manifest.js

@@ -6,12 +6,16 @@ module.exports = {
         path: "/docs/getting-started",
       },
       {
-        title: "Assistant",
+        title: "With Figma",
         open: true,
         routes: [
+          {
+            title: "Assistant",
+            path: "/docs/with-figma/assistant",
+          },
           {
             title: "Design Assistant",
-            path: "/docs/assistant/design-assistant",
+            path: "/docs/with-figma/assistant/design-assistant",
             routes: [
               {
                 title: "Icons loader",
@@ -21,31 +25,31 @@ module.exports = {
           },
           // {
           //   title: "Components View",
-          //   path: "/docs/assistant/components-view",
+          //   path: "/docs/with-figma/assistant/components-view",
           // },
           // {
           //   title: "Code View",
-          //   path: "/docs/assistant/code-view",
+          //   path: "/docs/with-figma/assistant/code-view",
           // },
           // {
           //   title: "Quick look",
-          //   path: "/docs/assistant/quicklook",
+          //   path: "/docs/with-figma/assistant/quicklook",
           // },
           // {
           //   title: "Click to copy",
-          //   path: "/docs/assistant/click-to-copy",
+          //   path: "/docs/with-figma/assistant/click-to-copy",
           // },
           // {
           //   title: "Design Linting",
-          //   path: "/docs/assistant/linter",
+          //   path: "/docs/with-figma/assistant/linter",
           // },
           // {
           //   title: "Preferences",
-          //   path: "/docs/assistant/preferences",
+          //   path: "/docs/with-figma/assistant/preferences",
           // },
           // {
           //   title: "Environment Variables",
-          //   path: "/docs/assistant/environment-variables",
+          //   path: "/docs/with-figma/assistant/environment-variables",
           // },
         ],
       },

apps/docs/package.json

@@ -18,11 +18,11 @@
     "write-translations": "docusaurus write-translations"
   },
   "dependencies": {
-    "@docusaurus/core": "3.9.2",
-    "@docusaurus/plugin-client-redirects": "3.9.2",
-    "@docusaurus/plugin-google-gtag": "3.9.2",
-    "@docusaurus/plugin-sitemap": "3.9.2",
-    "@docusaurus/preset-classic": "3.9.2",
+    "@docusaurus/core": "3.10.0",
+    "@docusaurus/plugin-client-redirects": "3.10.0",
+    "@docusaurus/plugin-google-gtag": "3.10.0",
+    "@docusaurus/plugin-sitemap": "3.10.0",
+    "@docusaurus/preset-classic": "3.10.0",
     "@mdx-js/react": "^3.1.0",
     "clsx": "^2.1.1",
     "katex": "^0.16.11",
@@ -33,9 +33,9 @@
     "remark-math": "^6.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.9.2",
-    "@docusaurus/tsconfig": "3.9.2",
-    "@docusaurus/types": "3.9.2",
+    "@docusaurus/module-type-aliases": "3.10.0",
+    "@docusaurus/tsconfig": "3.10.0",
+    "@docusaurus/types": "3.10.0",
     "fs-extra": "^10.0.0",
     "marked": "^4.0.10",
     "typescript": "^5"

apps/docs/scripts/docs-site-gen/copy-docs.js

@@ -15,7 +15,13 @@ function copyAll() {
   // deletions in the source tree do not leave duplicate routes (e.g. README
   // vs index) in the build output.
   fse.emptyDirSync(dest);
-  fse.copySync(origin, dest, { overwrite: true });
+  fse.copySync(origin, dest, {
+    overwrite: true,
+    filter: (src) => {
+      const base = path.basename(src);
+      return base !== ".DS_Store";
+    },
+  });
 }
 
 module.exports = copyAll;

apps/docs/sidebars.js

@@ -174,49 +174,30 @@ const api = [
   // },
 ];
 
-const flags = [
-  {
-    type: "autogenerated",
-    dirName: "flags",
-  },
-  ..._flags_items,
-];
-
 const docs = [
   {
     type: "doc",
     id: "intro",
   },
   {
     type: "category",
-    label: "Getting Started",
+    label: "Editor",
     collapsed: true,
     items: [
       {
         type: "autogenerated",
-        dirName: "getting-started",
+        dirName: "editor",
       },
     ],
   },
   {
     type: "category",
-    label: "Concepts",
+    label: "Forms",
     collapsed: true,
     items: [
       {
         type: "autogenerated",
-        dirName: "concepts",
-      },
-    ],
-  },
-  {
-    type: "category",
-    label: "Assistant",
-    collapsed: true,
-    items: [
-      {
-        type: "autogenerated",
-        dirName: "assistant",
+        dirName: "forms",
       },
     ],
   },
@@ -239,6 +220,39 @@ const docs = [
       },
     ],
   },
+  {
+    type: "category",
+    label: "With Figma",
+    collapsed: true,
+    items: [
+      {
+        type: "autogenerated",
+        dirName: "with-figma",
+      },
+    ],
+  },
+  {
+    type: "category",
+    label: "Design",
+    collapsed: true,
+    items: [
+      {
+        type: "autogenerated",
+        dirName: "design",
+      },
+    ],
+  },
+  {
+    type: "category",
+    label: "CLI",
+    collapsed: true,
+    items: [
+      {
+        type: "autogenerated",
+        dirName: "cli",
+      },
+    ],
+  },
   {
     type: "category",
     label: "Models",
@@ -285,7 +299,6 @@ const wg = [
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   tutorialSidebar: docs,
-  flagsSidebar: flags,
   togetherSidebar: together,
   apiSidebar: api,
   wgSidebar: wg,

apps/viewer/package.json

@@ -12,7 +12,7 @@
   "dependencies": {
     "@uidotdev/usehooks": "^2.4.1",
     "lucide-react": "^0.511.0",
-    "next": "16.1.6",
+    "next": "16.2.4",
     "pdfjs-dist": "4.8.69",
     "react": "19.2.3",
     "react-dom": "19.2.3",

docs/AGENTS.md

@@ -12,27 +12,39 @@ This directory is the **source of truth** for documentation content.
 
 ## Actively maintained
 
-We **only actively maintain** the following docs areas:
+The most actively maintained docs areas are:
 
 - `docs/wg/**` — working group docs (design notes, architecture, proposals, WIP)
 - `docs/reference/**` — reference docs (glossary, specs, stable technical references)
+- `docs/editor/**` — editor user and feature docs
+- `docs/forms/**` — forms docs
+- `docs/platform/**` — platform/product docs
+- `docs/with-figma/**` — Figma interoperability, guides, and Assistant product docs
+- `docs/design/**` — design-oriented product/reference docs
+- `docs/math/**` — supporting technical references
 
 ## SEO frontmatter
 
-For docs SEO/frontmatter cleanup, start with the actively maintained areas:
-`docs/wg/**` and `docs/reference/**`. Avoid broad repo-wide churn across
-older docs sections unless the task explicitly asks for that migration.
+For docs SEO/frontmatter cleanup, start with the actively maintained areas
+above. Avoid broad repo-wide churn across deprecated, synced, or archived
+sections unless the task explicitly asks for that migration.
 
 When adding or meaningfully editing an actively maintained doc page, prefer
 frontmatter with `title`, `description`, and `keywords`. For most `wg/` and
 `reference/` Markdown pages that do not use MDX/JSX features, also include
 `format: md` as described below.
 
-## Everything else
+## Special Cases
+
+Some docs trees are intentionally kept, but have different ownership rules:
 
-Other folders under `/docs` are **not actively managed**.
+- `docs/cli/**` is deprecated. Keep it unless the task explicitly removes or rewrites deprecated CLI docs.
+- `docs/@designto-code/**` is synced from an external source. Do not restructure or rewrite it unless the task explicitly targets that sync source.
+- `docs/_history/**` contains archived, code-facing record material. It is not part of the user-facing docs surface; if you archive new docs, move them under `_history/` and mark each page `unlisted: true`.
+
+## Everything else
 
-- Unless you have a specific task, **avoid editing** content outside `docs/wg/**` and `docs/reference/**`.
+- Unless you have a specific task, prefer edits in the actively maintained areas above.
 - Do not edit generated artifacts under `/apps/docs/docs/**`.
 
 ## Universal routing (linking to editor pages)
@@ -100,16 +112,19 @@ This prevents all MDX-related parsing issues for the entire file.
 
 ## Structure
 
-| directory                        | name          | description                                                            | active |
-| -------------------------------- | ------------- | ---------------------------------------------------------------------- | ------ |
-| [/docs/wg](./wg)                 | working group | working group documents, architecture documents, todo list, etc        | yes    |
-| [/docs/wg/format](./wg/format)   | format        | Grida IR spec and CSS/HTML/SVG import mapping trackers                 | yes    |
-| [/docs/reference](./reference)   | reference     | glossary and references (technical documents)                          | yes    |
-| [/docs/math](./math)             | math          | Math reference, used for internal docs referencing                     | yes    |
-| [/docs/platform](./platform)     | platform      | Grida Platform (API/Spec) documents                                    | yes    |
-| [/docs/editor](./editor)         | editor        | Grida Editor - User Documentation                                      | yes    |
-| [/docs/forms](./forms)           | forms         | Grida Forms - User Documentation                                       | yes    |
-| [/docs/canvas](./canvas)         | canvas        | Grida Canvas SDK - User Documentation                                  | no     |
-| [/docs/cli](./cli)               | cli           | Grida CLI - User Documentation                                         | yes    |
-| [/docs/together](./together)     | together      | Contributing, Support, Community, etc                                  | yes    |
-| [/docs/with-figma](./with-figma) | with-figma    | Grida with Figma - Grida <-> Figma compatibility and user guides | yes    |
+| directory                                | name           | description                                                            | active |
+| ---------------------------------------- | -------------- | ---------------------------------------------------------------------- | ------ |
+| [/docs/wg](./wg)                         | working group  | working group documents, architecture documents, todo list, etc        | yes    |
+| [/docs/wg/format](./wg/format)           | format         | Grida IR spec and CSS/HTML/SVG import mapping trackers                 | yes    |
+| [/docs/reference](./reference)           | reference      | glossary and references (technical documents)                          | yes    |
+| [/docs/math](./math)                     | math           | Math reference, used for internal docs referencing                     | yes    |
+| [/docs/platform](./platform)             | platform       | Grida Platform (API/Spec) documents                                    | yes    |
+| [/docs/editor](./editor)                 | editor         | Grida Editor - User Documentation                                      | yes    |
+| [/docs/forms](./forms)                   | forms          | Grida Forms - User Documentation                                       | yes    |
+| [/docs/with-figma](./with-figma)         | with-figma     | Grida with Figma - Grida <-> Figma compatibility and user guides | yes    |
+| [/docs/design](./design)                 | design         | Design-oriented docs and visual behavior notes                         | yes    |
+| [/docs/canvas](./canvas)                 | canvas         | Grida Canvas SDK - User Documentation                                  | no     |
+| [/docs/cli](./cli)                       | cli            | Deprecated CLI docs kept for compatibility                             | no     |
+| [/docs/@designto-code](./@designto-code) | design-to-code | Externally synced reference docs                                       | no     |
+| [/docs/\_history](./_history)            | history        | Archived, code-facing record docs not meant for user navigation        | no     |
+| [/docs/together](./together)             | together       | Contributing, Support, Community, etc                                  | no     |

docs/flags/index.md → docs/_history/flags/index.md

@@ -1,4 +1,5 @@
 ---
+unlisted: true
 id: intro
 title: "Introduction to Flags"
 sidebar_position: 1
@@ -30,7 +31,7 @@ Like in the example above, the `--artwork` flag is used to export the group as a
 <img />
 ```
 
-Learn more about [--artwork](../@designto-code/flags/--artwork)
+Learn more about [--artwork](../../@designto-code/flags/--artwork)
 
 <!-- this link is valid on docs site -->
 

docs/getting-started/01-intro.mdx → docs/_history/getting-started/01-intro.mdx

@@ -1,6 +1,7 @@
 ---
 id: intro
 title: "Installation"
+unlisted: true
 excerpt: "Convert your design to code to any platforms, learn how to make design work with Grida."
 ---
 

docs/getting-started/02-clean-design-for-clean-code.mdx → docs/_history/getting-started/02-clean-design-for-clean-code.mdx

@@ -1,6 +1,7 @@
 ---
 id: clean-design-for-clean-design
 title: "Clean Design for Clean Code"
+unlisted: true
 excerpt: "Clean your design, maximize the product quality"
 ---
 

docs/getting-started/03-configuration.mdx → docs/_history/getting-started/03-configuration.mdx

@@ -1,6 +1,7 @@
 ---
 id: configuration
 title: "Framework & Configuration"
+unlisted: true
 ---
 
 # Configuration

docs/getting-started/04-integrations.mdx → docs/_history/getting-started/04-integrations.mdx

@@ -1,6 +1,7 @@
 ---
 id: integrations
 title: "Integrations"
+unlisted: true
 ---
 
 # Integrations

docs/getting-started/05-examples.mdx → docs/_history/getting-started/05-examples.mdx

@@ -1,6 +1,7 @@
 ---
 id: examples
 title: "Examples"
+unlisted: true
 ---
 
 # Examples