Update button docs variant details

Purpose

The button variants are being paired down (see gitlab-org/gitlab-design#1263 (closed)) and we need to introduce the new Confirm button (getting added to GitLab UI in gitlab-org/gitlab-ui!1935 (merged)), and mention which variants will be deprecated.

This update will:

• Clarify button variants and their use.
• Note which buttons will be deprecated.
• Include the latest examples from GitLab UI.

/cc @gitlab-com/gitlab-ux/ux-foundations