picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/design-system.md

@@ -6,13 +6,14 @@ generated: true
 
 # Design system schema
 
-The operations and types that `design-system.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `designSystem`
 
-Get a design system by ID.
+Reads a design system.
+Scope: `ORGANIZATION_PROJECTS_READ`.
 
 ```graphql
 designSystem(id: ID!): DesignSystem @auth
@@ -20,19 +21,28 @@ designSystem(id: ID!): DesignSystem @auth
 
 ### `designSystems`
 
-List design systems in a project. Filter by name with `search`
-(case-insensitive substring) and order with `sortKey` (default `NAME`) plus
-`reverse`.
+Lists the design systems in a project.
+Scope: `ORGANIZATION_PROJECTS_READ`.
 
 ```graphql
-designSystems(projectId: ID!, first: Int, after: String, search: String, sortKey: DesignSystemSortKeys = NAME, reverse: Boolean = false): DesignSystemConnection! @auth
+designSystems(
+  projectId: ID!
+  first: Int
+  after: String
+  """Text that the name contains, ignoring case."""
+  search: String
+  sortKey: DesignSystemSortKeys = NAME
+  """Whether to reverse the order of `sortKey`."""
+  reverse: Boolean = false
+): DesignSystemConnection! @auth
 ```
 
 ## Mutations
 
 ### `designSystemCreate`
 
-Create a new design system. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates a design system from a committed Markdown asset.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 designSystemCreate(input: DesignSystemCreateInput!): DesignSystemCreatePayload! @auth
@@ -40,7 +50,8 @@ designSystemCreate(input: DesignSystemCreateInput!): DesignSystemCreatePayload!
 
 ### `designSystemUpdate`
 
-Update a design system. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates a design system's name or guidance asset.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 designSystemUpdate(input: DesignSystemUpdateInput!): DesignSystemUpdatePayload! @auth
@@ -48,7 +59,8 @@ designSystemUpdate(input: DesignSystemUpdateInput!): DesignSystemUpdatePayload!
 
 ### `designSystemDelete`
 
-Delete a design system. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes a design system. The asset that holds its guidance is kept.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 designSystemDelete(input: DesignSystemDeleteInput!): DesignSystemDeletePayload! @auth
@@ -60,22 +72,20 @@ designSystemDelete(input: DesignSystemDeleteInput!): DesignSystemDeletePayload!
 
 ```graphql
 """
-A project-level design guidance document. The markdown content lives in the
-referenced Asset; the row itself only carries the display name and the
-Asset link.
+A set of shared design decisions for a project, written as a Markdown file held in an asset.
 """
 type DesignSystem {
-  """Unique design system identifier."""
+  """The ID of the design system."""
   id: ID!
-  """Display name of the design system."""
+  """The name of the design system."""
   name: String!
-  """The project this design system belongs to."""
+  """The project that holds the design system."""
   project: Project!
-  """The markdown Asset holding the design guidance content."""
+  """The Markdown asset that holds the design guidance."""
   asset: Asset!
-  """When this design system was created."""
+  """When the design system was created."""
   createdAt: DateTime!
-  """When this design system was last updated."""
+  """When the design system last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -83,9 +93,9 @@ type DesignSystem {
 ### `DesignSystemEdge`
 
 ```graphql
-"""Edge type for `DesignSystemConnection`."""
+"""A design system in a page of results."""
 type DesignSystemEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The design system."""
   node: DesignSystem!
@@ -95,19 +105,17 @@ type DesignSystemEdge {
 ### `DesignSystemConnection`
 
 ```graphql
-"""
-Relay-style connection of design systems, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of design systems."""
 type DesignSystemConnection {
-  """List of design system edges."""
+  """The edges in this page."""
   edges: [DesignSystemEdge!]!
-  """
-  Flat list of design systems, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The design systems in this page."""
   nodes: [DesignSystem!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of design systems."""
+  """
+  The number of design systems in the project. `search` does not narrow it.
+  """
   totalCount: Int!
 }
 ```
@@ -115,17 +123,13 @@ type DesignSystemConnection {
 ### `DesignSystemSortKeys`
 
 ```graphql
-"""
-Sort keys for `designSystems(...)`. Pair with `reverse: true` to flip the
-order (`NAME` and `reverse: false` sorts A to Z; `CREATED_AT` and
-`reverse: true` is newest-first).
-"""
+"""The order of `designSystems`."""
 enum DesignSystemSortKeys {
-  """Sort by `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """Sort by `updatedAt`."""
+  """By last change, oldest first."""
   UPDATED_AT
 }
 ```
@@ -133,13 +137,15 @@ enum DesignSystemSortKeys {
 ### `DesignSystemCreateInput`
 
 ```graphql
-"""Input for `designSystemCreate`."""
+"""The input of `designSystemCreate`."""
 input DesignSystemCreateInput {
-  """Project ID to create the design system in."""
+  """The ID of the project to create the design system in."""
   projectId: ID!
-  """Display name for the design system."""
+  """The name of the design system. It must not be blank."""
   name: String!
-  """Committed Asset ID holding the markdown design guidance content."""
+  """
+  The ID of a committed Markdown asset in the same project that holds the design guidance.
+  """
   assetId: ID!
 }
 ```
@@ -147,7 +153,7 @@ input DesignSystemCreateInput {
 ### `DesignSystemCreatePayload`
 
 ```graphql
-"""Payload returned by `designSystemCreate`."""
+"""The result of `designSystemCreate`."""
 type DesignSystemCreatePayload {
   """The created design system."""
   designSystem: DesignSystem
@@ -157,13 +163,15 @@ type DesignSystemCreatePayload {
 ### `DesignSystemUpdateInput`
 
 ```graphql
-"""Input for `designSystemUpdate`. Omit a field to leave it unchanged."""
+"""The input of `designSystemUpdate`. Omit a field to keep its value."""
 input DesignSystemUpdateInput {
-  """Design system ID."""
+  """The ID of the design system. Required."""
   id: ID!
-  """New display name."""
+  """The new name."""
   name: String
-  """New committed Asset ID holding the markdown design guidance content."""
+  """
+  The ID of a committed Markdown asset in the same project that replaces the guidance.
+  """
   assetId: ID
 }
 ```
@@ -171,7 +179,7 @@ input DesignSystemUpdateInput {
 ### `DesignSystemUpdatePayload`
 
 ```graphql
-"""Payload returned by `designSystemUpdate`."""
+"""The result of `designSystemUpdate`."""
 type DesignSystemUpdatePayload {
   """The updated design system."""
   designSystem: DesignSystem
@@ -181,9 +189,9 @@ type DesignSystemUpdatePayload {
 ### `DesignSystemDeleteInput`
 
 ```graphql
-"""Input for `designSystemDelete`."""
+"""The input of `designSystemDelete`."""
 input DesignSystemDeleteInput {
-  """Design system ID."""
+  """The ID of the design system."""
   id: ID!
 }
 ```
@@ -191,9 +199,9 @@ input DesignSystemDeleteInput {
 ### `DesignSystemDeletePayload`
 
 ```graphql
-"""Payload returned by `designSystemDelete`."""
+"""The result of `designSystemDelete`."""
 type DesignSystemDeletePayload {
-  """ID of the deleted design system."""
+  """The ID of the deleted design system."""
   deletedDesignSystemId: ID
 }
 ```