docs: add naming and design guide

src/components/learn-aggregator/learn-pages.tsx

@@ -111,6 +111,12 @@ const _items: Record<
     icon: new URL("./assets/solve.svg", import.meta.url).href,
     section: "best-practices",
   },
+  "error-handling": {
+    description:
+      "Compare top-level errors and errors-as-data, and learn when to use each approach for exceptional versus expected failures.",
+    icon: new URL("./assets/construction.svg", import.meta.url).href,
+    section: "best-practices",
+  },
   "global-object-identification": {
     description:
       "Use globally unique IDs and the Node interface to enable caching, refetching, and efficient schema traversal.",
@@ -153,6 +159,12 @@ const _items: Record<
     icon: new URL("./assets/construction.svg", import.meta.url).href,
     section: "best-practices",
   },
+  "naming-design": {
+    description:
+      "Learn how to establish naming conventions and design standards for your GraphQL schema.",
+    icon: new URL("./assets/pen.svg", import.meta.url).href,
+    section: "best-practices",
+  },
 }
 
 const learnPages = _items as Record<LearnPagePath, LearnPageItem | null>

src/pages/learn/_meta.ts

@@ -32,11 +32,17 @@ export default {
   authorization: "",
   pagination: "",
   "schema-design": "Schema Design",
+  "error-handling": "Error Handling",
   "global-object-identification": "",
   caching: "",
   performance: "",
   security: "",
   federation: "",
   "robust-applications": "Robust Applications",
   "debug-errors": "Common GraphQL over HTTP Errors",
+  "-- 3": {
+    type: "separator",
+    title: "Schema Governance",
+  },
+  "naming-design": "Naming Conventions and Design Standards",
 }

src/pages/learn/error-handling.mdx

@@ -0,0 +1,59 @@
+# Error Handling
+
+GraphQL gives you two complementary ways to communicate errors to clients: the top-level `errors` array for exceptional failures, and errors-as-data for expected, domain-specific failures. Using the right approach for each situation keeps your API predictable and makes error states discoverable through the schema.
+
+## Use top-level errors for exceptional failures
+
+The standard GraphQL `errors` array handles infrastructure and system failures:
+
+```json
+{
+  "data": null,
+  "errors": [{
+    "message": "Database connection failed",
+    "extensions": {
+      "code": "INTERNAL_SERVER_ERROR"
+    }
+  }]
+}
+```
+
+## Use errors-as-data for domain errors
+
+Business logic errors belong in the schema as structured types:
+
+```graphql
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+}
+
+type CreateUserPayload {
+  user: User
+  userErrors: [UserError!]!
+}
+
+type UserError {
+  message: String!
+  field: [String!]
+  code: UserErrorCode!
+}
+
+enum UserErrorCode {
+  USERNAME_TAKEN
+  INVALID_EMAIL
+  PASSWORD_TOO_SHORT
+}
+```
+
+This pattern makes errors discoverable through introspection and provides type safety.
+
+## Choose based on whether errors are exceptional
+
+| Error type | Pattern | Example |
+|-----------|---------|---------|
+| Infrastructure failure | Top-level error | Database timeout, network error |
+| Invalid GraphQL | Top-level error | Syntax error, unknown field |
+| Authentication required | Top-level error | Missing auth token |
+| Business rule violation | errors-as-data | Username taken, invalid email |
+| Validation failure | errors-as-data | Required field missing |
+| Domain constraint | errors-as-data | Insufficient inventory |